Georg Brandl | 0f25cea | 2012-03-04 16:12:09 +0100 | [diff] [blame] | 1 | # -*- coding: utf-8 -*- |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 2 | # Autogenerated by Sphinx on Tue Jan 30 18:36:07 2018 |
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' |
| 29 | 'line option -O). The current code generator emits no code for an\n' |
| 30 | 'assert statement when optimization is requested at compile time. ' |
| 31 | 'Note\n' |
| 32 | 'that it is unnecessary to include the source code for the ' |
| 33 | 'expression\n' |
| 34 | 'that failed in the error message; it will be displayed as part of ' |
| 35 | 'the\n' |
| 36 | 'stack trace.\n' |
| 37 | '\n' |
| 38 | 'Assignments to "__debug__" are illegal. The value for the ' |
| 39 | 'built-in\n' |
| 40 | 'variable is determined when the interpreter starts.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 41 | 'assignment': 'Assignment statements\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 42 | '*********************\n' |
| 43 | '\n' |
| 44 | 'Assignment statements are used to (re)bind names to values and ' |
| 45 | 'to\n' |
| 46 | 'modify attributes or items of mutable objects:\n' |
| 47 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 48 | ' assignment_stmt ::= (target_list "=")+ (starred_expression ' |
| 49 | '| yield_expression)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 50 | ' target_list ::= target ("," target)* [","]\n' |
| 51 | ' target ::= identifier\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 52 | ' | "(" [target_list] ")"\n' |
| 53 | ' | "[" [target_list] "]"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 54 | ' | attributeref\n' |
| 55 | ' | subscription\n' |
| 56 | ' | slicing\n' |
| 57 | ' | "*" target\n' |
| 58 | '\n' |
| 59 | '(See section Primaries for the syntax definitions for ' |
| 60 | '*attributeref*,\n' |
| 61 | '*subscription*, and *slicing*.)\n' |
| 62 | '\n' |
| 63 | 'An assignment statement evaluates the expression list ' |
| 64 | '(remember that\n' |
| 65 | 'this can be a single expression or a comma-separated list, the ' |
| 66 | 'latter\n' |
| 67 | 'yielding a tuple) and assigns the single resulting object to ' |
| 68 | 'each of\n' |
| 69 | 'the target lists, from left to right.\n' |
| 70 | '\n' |
| 71 | 'Assignment is defined recursively depending on the form of the ' |
| 72 | 'target\n' |
| 73 | '(list). When a target is part of a mutable object (an ' |
| 74 | 'attribute\n' |
| 75 | 'reference, subscription or slicing), the mutable object must\n' |
| 76 | 'ultimately perform the assignment and decide about its ' |
| 77 | 'validity, and\n' |
| 78 | 'may raise an exception if the assignment is unacceptable. The ' |
| 79 | 'rules\n' |
| 80 | 'observed by various types and the exceptions raised are given ' |
| 81 | 'with the\n' |
| 82 | 'definition of the object types (see section The standard type\n' |
| 83 | 'hierarchy).\n' |
| 84 | '\n' |
| 85 | 'Assignment of an object to a target list, optionally enclosed ' |
| 86 | 'in\n' |
| 87 | 'parentheses or square brackets, is recursively defined as ' |
| 88 | 'follows.\n' |
| 89 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 90 | '* If the target list is empty: The object must also be an ' |
| 91 | 'empty\n' |
| 92 | ' iterable.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 93 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 94 | '* If the target list is a single target in parentheses: The ' |
| 95 | 'object\n' |
| 96 | ' is assigned to that target.\n' |
| 97 | '\n' |
| 98 | '* If the target list is a comma-separated list of targets, or ' |
| 99 | 'a\n' |
| 100 | ' single target in square brackets: The object must be an ' |
| 101 | 'iterable\n' |
| 102 | ' with the same number of items as there are targets in the ' |
| 103 | 'target\n' |
| 104 | ' list, and the items are assigned, from left to right, to ' |
| 105 | 'the\n' |
| 106 | ' corresponding targets.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 107 | '\n' |
| 108 | ' * If the target list contains one target prefixed with an\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 109 | ' asterisk, called a "starred" target: The object must be ' |
| 110 | 'an\n' |
| 111 | ' iterable with at least as many items as there are targets ' |
| 112 | 'in the\n' |
| 113 | ' target list, minus one. The first items of the iterable ' |
| 114 | 'are\n' |
| 115 | ' assigned, from left to right, to the targets before the ' |
| 116 | 'starred\n' |
| 117 | ' target. The final items of the iterable are assigned to ' |
| 118 | 'the\n' |
| 119 | ' targets after the starred target. A list of the remaining ' |
| 120 | 'items\n' |
| 121 | ' in the iterable is then assigned to the starred target ' |
| 122 | '(the list\n' |
| 123 | ' can be empty).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 124 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 125 | ' * Else: The object must be an iterable with the same number ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 126 | 'of\n' |
| 127 | ' items as there are targets in the target list, and the ' |
| 128 | 'items are\n' |
| 129 | ' assigned, from left to right, to the corresponding ' |
| 130 | 'targets.\n' |
| 131 | '\n' |
| 132 | 'Assignment of an object to a single target is recursively ' |
| 133 | 'defined as\n' |
| 134 | 'follows.\n' |
| 135 | '\n' |
| 136 | '* If the target is an identifier (name):\n' |
| 137 | '\n' |
| 138 | ' * If the name does not occur in a "global" or "nonlocal" ' |
| 139 | 'statement\n' |
| 140 | ' in the current code block: the name is bound to the object ' |
| 141 | 'in the\n' |
| 142 | ' current local namespace.\n' |
| 143 | '\n' |
| 144 | ' * Otherwise: the name is bound to the object in the global\n' |
| 145 | ' namespace or the outer namespace determined by ' |
| 146 | '"nonlocal",\n' |
| 147 | ' respectively.\n' |
| 148 | '\n' |
| 149 | ' The name is rebound if it was already bound. This may cause ' |
| 150 | 'the\n' |
| 151 | ' reference count for the object previously bound to the name ' |
| 152 | 'to reach\n' |
| 153 | ' zero, causing the object to be deallocated and its ' |
| 154 | 'destructor (if it\n' |
| 155 | ' has one) to be called.\n' |
| 156 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 157 | '* If the target is an attribute reference: The primary ' |
| 158 | 'expression in\n' |
| 159 | ' the reference is evaluated. It should yield an object with\n' |
| 160 | ' assignable attributes; if this is not the case, "TypeError" ' |
| 161 | 'is\n' |
| 162 | ' raised. That object is then asked to assign the assigned ' |
| 163 | 'object to\n' |
| 164 | ' the given attribute; if it cannot perform the assignment, it ' |
| 165 | 'raises\n' |
| 166 | ' an exception (usually but not necessarily ' |
| 167 | '"AttributeError").\n' |
| 168 | '\n' |
| 169 | ' Note: If the object is a class instance and the attribute ' |
| 170 | 'reference\n' |
| 171 | ' occurs on both sides of the assignment operator, the RHS ' |
| 172 | 'expression,\n' |
| 173 | ' "a.x" can access either an instance attribute or (if no ' |
| 174 | 'instance\n' |
| 175 | ' attribute exists) a class attribute. The LHS target "a.x" ' |
| 176 | 'is always\n' |
| 177 | ' set as an instance attribute, creating it if necessary. ' |
| 178 | 'Thus, the\n' |
| 179 | ' two occurrences of "a.x" do not necessarily refer to the ' |
| 180 | 'same\n' |
| 181 | ' attribute: if the RHS expression refers to a class ' |
| 182 | 'attribute, the\n' |
| 183 | ' LHS creates a new instance attribute as the target of the\n' |
| 184 | ' assignment:\n' |
| 185 | '\n' |
| 186 | ' class Cls:\n' |
| 187 | ' x = 3 # class variable\n' |
| 188 | ' inst = Cls()\n' |
| 189 | ' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x ' |
| 190 | 'as 3\n' |
| 191 | '\n' |
| 192 | ' This description does not necessarily apply to descriptor\n' |
| 193 | ' attributes, such as properties created with "property()".\n' |
| 194 | '\n' |
| 195 | '* If the target is a subscription: The primary expression in ' |
| 196 | 'the\n' |
| 197 | ' reference is evaluated. It should yield either a mutable ' |
| 198 | 'sequence\n' |
| 199 | ' object (such as a list) or a mapping object (such as a ' |
| 200 | 'dictionary).\n' |
| 201 | ' Next, the subscript expression is evaluated.\n' |
| 202 | '\n' |
| 203 | ' If the primary is a mutable sequence object (such as a ' |
| 204 | 'list), the\n' |
| 205 | ' subscript must yield an integer. If it is negative, the ' |
| 206 | "sequence's\n" |
| 207 | ' length is added to it. The resulting value must be a ' |
| 208 | 'nonnegative\n' |
| 209 | " integer less than the sequence's length, and the sequence is " |
| 210 | 'asked\n' |
| 211 | ' to assign the assigned object to its item with that index. ' |
| 212 | 'If the\n' |
| 213 | ' index is out of range, "IndexError" is raised (assignment to ' |
| 214 | 'a\n' |
| 215 | ' subscripted sequence cannot add new items to a list).\n' |
| 216 | '\n' |
| 217 | ' If the primary is a mapping object (such as a dictionary), ' |
| 218 | 'the\n' |
| 219 | " subscript must have a type compatible with the mapping's key " |
| 220 | 'type,\n' |
| 221 | ' and the mapping is then asked to create a key/datum pair ' |
| 222 | 'which maps\n' |
| 223 | ' the subscript to the assigned object. This can either ' |
| 224 | 'replace an\n' |
| 225 | ' existing key/value pair with the same key value, or insert a ' |
| 226 | 'new\n' |
| 227 | ' key/value pair (if no key with the same value existed).\n' |
| 228 | '\n' |
| 229 | ' For user-defined objects, the "__setitem__()" method is ' |
| 230 | 'called with\n' |
| 231 | ' appropriate arguments.\n' |
| 232 | '\n' |
| 233 | '* If the target is a slicing: The primary expression in the\n' |
| 234 | ' reference is evaluated. It should yield a mutable sequence ' |
| 235 | 'object\n' |
| 236 | ' (such as a list). The assigned object should be a sequence ' |
| 237 | 'object\n' |
| 238 | ' of the same type. Next, the lower and upper bound ' |
| 239 | 'expressions are\n' |
| 240 | ' evaluated, insofar they are present; defaults are zero and ' |
| 241 | 'the\n' |
| 242 | " sequence's length. The bounds should evaluate to integers. " |
| 243 | 'If\n' |
| 244 | " either bound is negative, the sequence's length is added to " |
| 245 | 'it. The\n' |
| 246 | ' resulting bounds are clipped to lie between zero and the ' |
| 247 | "sequence's\n" |
| 248 | ' length, inclusive. Finally, the sequence object is asked to ' |
| 249 | 'replace\n' |
| 250 | ' the slice with the items of the assigned sequence. The ' |
| 251 | 'length of\n' |
| 252 | ' the slice may be different from the length of the assigned ' |
| 253 | 'sequence,\n' |
| 254 | ' thus changing the length of the target sequence, if the ' |
| 255 | 'target\n' |
| 256 | ' sequence allows it.\n' |
| 257 | '\n' |
| 258 | '**CPython implementation detail:** In the current ' |
| 259 | 'implementation, the\n' |
| 260 | 'syntax for targets is taken to be the same as for expressions, ' |
| 261 | 'and\n' |
| 262 | 'invalid syntax is rejected during the code generation phase, ' |
| 263 | 'causing\n' |
| 264 | 'less detailed error messages.\n' |
| 265 | '\n' |
| 266 | 'Although the definition of assignment implies that overlaps ' |
| 267 | 'between\n' |
| 268 | "the left-hand side and the right-hand side are 'simultaneous' " |
| 269 | '(for\n' |
| 270 | 'example "a, b = b, a" swaps two variables), overlaps *within* ' |
| 271 | 'the\n' |
| 272 | 'collection of assigned-to variables occur left-to-right, ' |
| 273 | 'sometimes\n' |
| 274 | 'resulting in confusion. For instance, the following program ' |
| 275 | 'prints\n' |
| 276 | '"[0, 2]":\n' |
| 277 | '\n' |
| 278 | ' x = [0, 1]\n' |
| 279 | ' i = 0\n' |
| 280 | ' i, x[i] = 1, 2 # i is updated, then x[i] is ' |
| 281 | 'updated\n' |
| 282 | ' print(x)\n' |
| 283 | '\n' |
| 284 | 'See also:\n' |
| 285 | '\n' |
| 286 | ' **PEP 3132** - Extended Iterable Unpacking\n' |
| 287 | ' The specification for the "*target" feature.\n' |
| 288 | '\n' |
| 289 | '\n' |
| 290 | 'Augmented assignment statements\n' |
| 291 | '===============================\n' |
| 292 | '\n' |
| 293 | 'Augmented assignment is the combination, in a single ' |
| 294 | 'statement, of a\n' |
| 295 | 'binary operation and an assignment statement:\n' |
| 296 | '\n' |
| 297 | ' augmented_assignment_stmt ::= augtarget augop ' |
| 298 | '(expression_list | yield_expression)\n' |
| 299 | ' augtarget ::= identifier | attributeref | ' |
| 300 | 'subscription | slicing\n' |
| 301 | ' augop ::= "+=" | "-=" | "*=" | "@=" | ' |
| 302 | '"/=" | "//=" | "%=" | "**="\n' |
| 303 | ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' |
| 304 | '\n' |
| 305 | '(See section Primaries for the syntax definitions of the last ' |
| 306 | 'three\n' |
| 307 | 'symbols.)\n' |
| 308 | '\n' |
| 309 | 'An augmented assignment evaluates the target (which, unlike ' |
| 310 | 'normal\n' |
| 311 | 'assignment statements, cannot be an unpacking) and the ' |
| 312 | 'expression\n' |
| 313 | 'list, performs the binary operation specific to the type of ' |
| 314 | 'assignment\n' |
| 315 | 'on the two operands, and assigns the result to the original ' |
| 316 | 'target.\n' |
| 317 | 'The target is only evaluated once.\n' |
| 318 | '\n' |
| 319 | 'An augmented assignment expression like "x += 1" can be ' |
| 320 | 'rewritten as\n' |
| 321 | '"x = x + 1" to achieve a similar, but not exactly equal ' |
| 322 | 'effect. In the\n' |
| 323 | 'augmented version, "x" is only evaluated once. Also, when ' |
| 324 | 'possible,\n' |
| 325 | 'the actual operation is performed *in-place*, meaning that ' |
| 326 | 'rather than\n' |
| 327 | 'creating a new object and assigning that to the target, the ' |
| 328 | 'old object\n' |
| 329 | 'is modified instead.\n' |
| 330 | '\n' |
| 331 | 'Unlike normal assignments, augmented assignments evaluate the ' |
| 332 | 'left-\n' |
| 333 | 'hand side *before* evaluating the right-hand side. For ' |
| 334 | 'example, "a[i]\n' |
| 335 | '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' |
| 336 | 'performs\n' |
| 337 | 'the addition, and lastly, it writes the result back to ' |
| 338 | '"a[i]".\n' |
| 339 | '\n' |
| 340 | 'With the exception of assigning to tuples and multiple targets ' |
| 341 | 'in a\n' |
| 342 | 'single statement, the assignment done by augmented assignment\n' |
| 343 | 'statements is handled the same way as normal assignments. ' |
| 344 | 'Similarly,\n' |
| 345 | 'with the exception of the possible *in-place* behavior, the ' |
| 346 | 'binary\n' |
| 347 | 'operation performed by augmented assignment is the same as the ' |
| 348 | 'normal\n' |
| 349 | 'binary operations.\n' |
| 350 | '\n' |
| 351 | 'For targets which are attribute references, the same caveat ' |
| 352 | 'about\n' |
| 353 | 'class and instance attributes applies as for regular ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 354 | 'assignments.\n' |
| 355 | '\n' |
| 356 | '\n' |
| 357 | 'Annotated assignment statements\n' |
| 358 | '===============================\n' |
| 359 | '\n' |
| 360 | 'Annotation assignment is the combination, in a single ' |
| 361 | 'statement, of a\n' |
| 362 | 'variable or attribute annotation and an optional assignment ' |
| 363 | 'statement:\n' |
| 364 | '\n' |
| 365 | ' annotated_assignment_stmt ::= augtarget ":" expression ["=" ' |
| 366 | 'expression]\n' |
| 367 | '\n' |
| 368 | 'The difference from normal Assignment statements is that only ' |
| 369 | 'single\n' |
| 370 | 'target and only single right hand side value is allowed.\n' |
| 371 | '\n' |
| 372 | 'For simple names as assignment targets, if in class or module ' |
| 373 | 'scope,\n' |
| 374 | 'the annotations are evaluated and stored in a special class or ' |
| 375 | 'module\n' |
| 376 | 'attribute "__annotations__" that is a dictionary mapping from ' |
| 377 | 'variable\n' |
| 378 | 'names (mangled if private) to evaluated annotations. This ' |
| 379 | 'attribute is\n' |
| 380 | 'writable and is automatically created at the start of class or ' |
| 381 | 'module\n' |
| 382 | 'body execution, if annotations are found statically.\n' |
| 383 | '\n' |
| 384 | 'For expressions as assignment targets, the annotations are ' |
| 385 | 'evaluated\n' |
| 386 | 'if in class or module scope, but not stored.\n' |
| 387 | '\n' |
| 388 | 'If a name is annotated in a function scope, then this name is ' |
| 389 | 'local\n' |
| 390 | 'for that scope. Annotations are never evaluated and stored in ' |
| 391 | 'function\n' |
| 392 | 'scopes.\n' |
| 393 | '\n' |
| 394 | 'If the right hand side is present, an annotated assignment ' |
| 395 | 'performs\n' |
| 396 | 'the actual assignment before evaluating annotations (where\n' |
| 397 | 'applicable). If the right hand side is not present for an ' |
| 398 | 'expression\n' |
| 399 | 'target, then the interpreter evaluates the target except for ' |
| 400 | 'the last\n' |
| 401 | '"__setitem__()" or "__setattr__()" call.\n' |
| 402 | '\n' |
| 403 | 'See also: **PEP 526** - Variable and attribute annotation ' |
| 404 | 'syntax\n' |
| 405 | ' **PEP 484** - Type hints\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 406 | 'atom-identifiers': 'Identifiers (Names)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 407 | '*******************\n' |
| 408 | '\n' |
| 409 | 'An identifier occurring as an atom is a name. See ' |
| 410 | 'section Identifiers\n' |
| 411 | 'and keywords for lexical definition and section Naming ' |
| 412 | 'and binding for\n' |
| 413 | 'documentation of naming and binding.\n' |
| 414 | '\n' |
| 415 | 'When the name is bound to an object, evaluation of the ' |
| 416 | 'atom yields\n' |
| 417 | 'that object. When a name is not bound, an attempt to ' |
| 418 | 'evaluate it\n' |
| 419 | 'raises a "NameError" exception.\n' |
| 420 | '\n' |
| 421 | '**Private name mangling:** When an identifier that ' |
| 422 | 'textually occurs in\n' |
| 423 | 'a class definition begins with two or more underscore ' |
| 424 | 'characters and\n' |
| 425 | 'does not end in two or more underscores, it is ' |
| 426 | 'considered a *private\n' |
| 427 | 'name* of that class. Private names are transformed to a ' |
| 428 | 'longer form\n' |
| 429 | 'before code is generated for them. The transformation ' |
| 430 | 'inserts the\n' |
| 431 | 'class name, with leading underscores removed and a ' |
| 432 | 'single underscore\n' |
| 433 | 'inserted, in front of the name. For example, the ' |
| 434 | 'identifier "__spam"\n' |
| 435 | 'occurring in a class named "Ham" will be transformed to ' |
| 436 | '"_Ham__spam".\n' |
| 437 | 'This transformation is independent of the syntactical ' |
| 438 | 'context in which\n' |
| 439 | 'the identifier is used. If the transformed name is ' |
| 440 | 'extremely long\n' |
| 441 | '(longer than 255 characters), implementation defined ' |
| 442 | 'truncation may\n' |
| 443 | 'happen. If the class name consists only of underscores, ' |
| 444 | 'no\n' |
| 445 | 'transformation is done.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 446 | 'atom-literals': 'Literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 447 | '********\n' |
| 448 | '\n' |
| 449 | 'Python supports string and bytes literals and various ' |
| 450 | 'numeric\n' |
| 451 | 'literals:\n' |
| 452 | '\n' |
| 453 | ' literal ::= stringliteral | bytesliteral\n' |
| 454 | ' | integer | floatnumber | imagnumber\n' |
| 455 | '\n' |
| 456 | 'Evaluation of a literal yields an object of the given type ' |
| 457 | '(string,\n' |
| 458 | 'bytes, integer, floating point number, complex number) with ' |
| 459 | 'the given\n' |
| 460 | 'value. The value may be approximated in the case of ' |
| 461 | 'floating point\n' |
| 462 | 'and imaginary (complex) literals. See section Literals for ' |
| 463 | 'details.\n' |
| 464 | '\n' |
| 465 | 'All literals correspond to immutable data types, and hence ' |
| 466 | 'the\n' |
| 467 | "object's identity is less important than its value. " |
| 468 | 'Multiple\n' |
| 469 | 'evaluations of literals with the same value (either the ' |
| 470 | 'same\n' |
| 471 | 'occurrence in the program text or a different occurrence) ' |
| 472 | 'may obtain\n' |
| 473 | 'the same object or a different object with the same ' |
| 474 | 'value.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 475 | 'attribute-access': 'Customizing attribute access\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 476 | '****************************\n' |
| 477 | '\n' |
| 478 | 'The following methods can be defined to customize the ' |
| 479 | 'meaning of\n' |
| 480 | 'attribute access (use of, assignment to, or deletion of ' |
| 481 | '"x.name") for\n' |
| 482 | 'class instances.\n' |
| 483 | '\n' |
| 484 | 'object.__getattr__(self, name)\n' |
| 485 | '\n' |
| 486 | ' Called when an attribute lookup has not found the ' |
| 487 | 'attribute in the\n' |
| 488 | ' usual places (i.e. it is not an instance attribute ' |
| 489 | 'nor is it found\n' |
| 490 | ' in the class tree for "self"). "name" is the ' |
| 491 | 'attribute name. This\n' |
| 492 | ' method should return the (computed) attribute value ' |
| 493 | 'or raise an\n' |
| 494 | ' "AttributeError" exception.\n' |
| 495 | '\n' |
| 496 | ' Note that if the attribute is found through the ' |
| 497 | 'normal mechanism,\n' |
| 498 | ' "__getattr__()" is not called. (This is an ' |
| 499 | 'intentional asymmetry\n' |
| 500 | ' between "__getattr__()" and "__setattr__()".) This is ' |
| 501 | 'done both for\n' |
| 502 | ' efficiency reasons and because otherwise ' |
| 503 | '"__getattr__()" would have\n' |
| 504 | ' no way to access other attributes of the instance. ' |
| 505 | 'Note that at\n' |
| 506 | ' least for instance variables, you can fake total ' |
| 507 | 'control by not\n' |
| 508 | ' inserting any values in the instance attribute ' |
| 509 | 'dictionary (but\n' |
| 510 | ' instead inserting them in another object). See the\n' |
| 511 | ' "__getattribute__()" method below for a way to ' |
| 512 | 'actually get total\n' |
| 513 | ' control over attribute access.\n' |
| 514 | '\n' |
| 515 | 'object.__getattribute__(self, name)\n' |
| 516 | '\n' |
| 517 | ' Called unconditionally to implement attribute ' |
| 518 | 'accesses for\n' |
| 519 | ' instances of the class. If the class also defines ' |
| 520 | '"__getattr__()",\n' |
| 521 | ' the latter will not be called unless ' |
| 522 | '"__getattribute__()" either\n' |
| 523 | ' calls it explicitly or raises an "AttributeError". ' |
| 524 | 'This method\n' |
| 525 | ' should return the (computed) attribute value or raise ' |
| 526 | 'an\n' |
| 527 | ' "AttributeError" exception. In order to avoid ' |
| 528 | 'infinite recursion in\n' |
| 529 | ' this method, its implementation should always call ' |
| 530 | 'the base class\n' |
| 531 | ' method with the same name to access any attributes it ' |
| 532 | 'needs, for\n' |
| 533 | ' example, "object.__getattribute__(self, name)".\n' |
| 534 | '\n' |
| 535 | ' Note: This method may still be bypassed when looking ' |
| 536 | 'up special\n' |
| 537 | ' methods as the result of implicit invocation via ' |
| 538 | 'language syntax\n' |
| 539 | ' or built-in functions. See Special method lookup.\n' |
| 540 | '\n' |
| 541 | 'object.__setattr__(self, name, value)\n' |
| 542 | '\n' |
| 543 | ' Called when an attribute assignment is attempted. ' |
| 544 | 'This is called\n' |
| 545 | ' instead of the normal mechanism (i.e. store the value ' |
| 546 | 'in the\n' |
| 547 | ' instance dictionary). *name* is the attribute name, ' |
| 548 | '*value* is the\n' |
| 549 | ' value to be assigned to it.\n' |
| 550 | '\n' |
| 551 | ' If "__setattr__()" wants to assign to an instance ' |
| 552 | 'attribute, it\n' |
| 553 | ' should call the base class method with the same name, ' |
| 554 | 'for example,\n' |
| 555 | ' "object.__setattr__(self, name, value)".\n' |
| 556 | '\n' |
| 557 | 'object.__delattr__(self, name)\n' |
| 558 | '\n' |
| 559 | ' Like "__setattr__()" but for attribute deletion ' |
| 560 | 'instead of\n' |
| 561 | ' assignment. This should only be implemented if "del ' |
| 562 | 'obj.name" is\n' |
| 563 | ' meaningful for the object.\n' |
| 564 | '\n' |
| 565 | 'object.__dir__(self)\n' |
| 566 | '\n' |
| 567 | ' Called when "dir()" is called on the object. A ' |
| 568 | 'sequence must be\n' |
| 569 | ' returned. "dir()" converts the returned sequence to a ' |
| 570 | 'list and\n' |
| 571 | ' sorts it.\n' |
| 572 | '\n' |
| 573 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 574 | 'Customizing module attribute access\n' |
| 575 | '===================================\n' |
| 576 | '\n' |
| 577 | 'Special names "__getattr__" and "__dir__" can be also ' |
| 578 | 'used to\n' |
| 579 | 'customize access to module attributes. The "__getattr__" ' |
| 580 | 'function at\n' |
| 581 | 'the module level should accept one argument which is the ' |
| 582 | 'name of an\n' |
| 583 | 'attribute and return the computed value or raise an ' |
| 584 | '"AttributeError".\n' |
| 585 | 'If an attribute is not found on a module object through ' |
| 586 | 'the normal\n' |
| 587 | 'lookup, i.e. "object.__getattribute__()", then ' |
| 588 | '"__getattr__" is\n' |
| 589 | 'searched in the module "__dict__" before raising an ' |
| 590 | '"AttributeError".\n' |
| 591 | 'If found, it is called with the attribute name and the ' |
| 592 | 'result is\n' |
| 593 | 'returned.\n' |
| 594 | '\n' |
| 595 | 'The "__dir__" function should accept no arguments, and ' |
| 596 | 'return a list\n' |
| 597 | 'of strings that represents the names accessible on ' |
| 598 | 'module. If present,\n' |
| 599 | 'this function overrides the standard "dir()" search on a ' |
| 600 | 'module.\n' |
| 601 | '\n' |
| 602 | 'For a more fine grained customization of the module ' |
| 603 | 'behavior (setting\n' |
| 604 | 'attributes, properties, etc.), one can set the ' |
| 605 | '"__class__" attribute\n' |
| 606 | 'of a module object to a subclass of "types.ModuleType". ' |
| 607 | 'For example:\n' |
| 608 | '\n' |
| 609 | ' import sys\n' |
| 610 | ' from types import ModuleType\n' |
| 611 | '\n' |
| 612 | ' class VerboseModule(ModuleType):\n' |
| 613 | ' def __repr__(self):\n' |
| 614 | " return f'Verbose {self.__name__}'\n" |
| 615 | '\n' |
| 616 | ' def __setattr__(self, attr, value):\n' |
| 617 | " print(f'Setting {attr}...')\n" |
| 618 | ' setattr(self, attr, value)\n' |
| 619 | '\n' |
| 620 | ' sys.modules[__name__].__class__ = VerboseModule\n' |
| 621 | '\n' |
| 622 | 'Note: Defining module "__getattr__" and setting module ' |
| 623 | '"__class__"\n' |
| 624 | ' only affect lookups made using the attribute access ' |
| 625 | 'syntax --\n' |
| 626 | ' directly accessing the module globals (whether by code ' |
| 627 | 'within the\n' |
| 628 | " module, or via a reference to the module's globals " |
| 629 | 'dictionary) is\n' |
| 630 | ' unaffected.\n' |
| 631 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 632 | 'Changed in version 3.5: "__class__" module attribute is ' |
| 633 | 'now writable.\n' |
| 634 | '\n' |
| 635 | 'New in version 3.7: "__getattr__" and "__dir__" module ' |
| 636 | 'attributes.\n' |
| 637 | '\n' |
| 638 | 'See also:\n' |
| 639 | '\n' |
| 640 | ' **PEP 562** - Module __getattr__ and __dir__\n' |
| 641 | ' Describes the "__getattr__" and "__dir__" functions ' |
| 642 | 'on modules.\n' |
| 643 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 644 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 645 | 'Implementing Descriptors\n' |
| 646 | '========================\n' |
| 647 | '\n' |
| 648 | 'The following methods only apply when an instance of the ' |
| 649 | 'class\n' |
| 650 | 'containing the method (a so-called *descriptor* class) ' |
| 651 | 'appears in an\n' |
| 652 | '*owner* class (the descriptor must be in either the ' |
| 653 | "owner's class\n" |
| 654 | 'dictionary or in the class dictionary for one of its ' |
| 655 | 'parents). In the\n' |
| 656 | 'examples below, "the attribute" refers to the attribute ' |
| 657 | 'whose name is\n' |
| 658 | "the key of the property in the owner class' " |
| 659 | '"__dict__".\n' |
| 660 | '\n' |
| 661 | 'object.__get__(self, instance, owner)\n' |
| 662 | '\n' |
| 663 | ' Called to get the attribute of the owner class (class ' |
| 664 | 'attribute\n' |
| 665 | ' access) or of an instance of that class (instance ' |
| 666 | 'attribute\n' |
| 667 | ' access). *owner* is always the owner class, while ' |
| 668 | '*instance* is the\n' |
| 669 | ' instance that the attribute was accessed through, or ' |
| 670 | '"None" when\n' |
| 671 | ' the attribute is accessed through the *owner*. This ' |
| 672 | 'method should\n' |
| 673 | ' return the (computed) attribute value or raise an ' |
| 674 | '"AttributeError"\n' |
| 675 | ' exception.\n' |
| 676 | '\n' |
| 677 | 'object.__set__(self, instance, value)\n' |
| 678 | '\n' |
| 679 | ' Called to set the attribute on an instance *instance* ' |
| 680 | 'of the owner\n' |
| 681 | ' class to a new value, *value*.\n' |
| 682 | '\n' |
| 683 | 'object.__delete__(self, instance)\n' |
| 684 | '\n' |
| 685 | ' Called to delete the attribute on an instance ' |
| 686 | '*instance* of the\n' |
| 687 | ' owner class.\n' |
| 688 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 689 | 'object.__set_name__(self, owner, name)\n' |
| 690 | '\n' |
| 691 | ' Called at the time the owning class *owner* is ' |
| 692 | 'created. The\n' |
| 693 | ' descriptor has been assigned to *name*.\n' |
| 694 | '\n' |
| 695 | ' New in version 3.6.\n' |
| 696 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 697 | 'The attribute "__objclass__" is interpreted by the ' |
| 698 | '"inspect" module as\n' |
| 699 | 'specifying the class where this object was defined ' |
| 700 | '(setting this\n' |
| 701 | 'appropriately can assist in runtime introspection of ' |
| 702 | 'dynamic class\n' |
| 703 | 'attributes). For callables, it may indicate that an ' |
| 704 | 'instance of the\n' |
| 705 | 'given type (or a subclass) is expected or required as ' |
| 706 | 'the first\n' |
| 707 | 'positional argument (for example, CPython sets this ' |
| 708 | 'attribute for\n' |
| 709 | 'unbound methods that are implemented in C).\n' |
| 710 | '\n' |
| 711 | '\n' |
| 712 | 'Invoking Descriptors\n' |
| 713 | '====================\n' |
| 714 | '\n' |
| 715 | 'In general, a descriptor is an object attribute with ' |
| 716 | '"binding\n' |
| 717 | 'behavior", one whose attribute access has been ' |
| 718 | 'overridden by methods\n' |
| 719 | 'in the descriptor protocol: "__get__()", "__set__()", ' |
| 720 | 'and\n' |
| 721 | '"__delete__()". If any of those methods are defined for ' |
| 722 | 'an object, it\n' |
| 723 | 'is said to be a descriptor.\n' |
| 724 | '\n' |
| 725 | 'The default behavior for attribute access is to get, ' |
| 726 | 'set, or delete\n' |
| 727 | "the attribute from an object's dictionary. For instance, " |
| 728 | '"a.x" has a\n' |
| 729 | 'lookup chain starting with "a.__dict__[\'x\']", then\n' |
| 730 | '"type(a).__dict__[\'x\']", and continuing through the ' |
| 731 | 'base classes of\n' |
| 732 | '"type(a)" excluding metaclasses.\n' |
| 733 | '\n' |
| 734 | 'However, if the looked-up value is an object defining ' |
| 735 | 'one of the\n' |
| 736 | 'descriptor methods, then Python may override the default ' |
| 737 | 'behavior and\n' |
| 738 | 'invoke the descriptor method instead. Where this occurs ' |
| 739 | 'in the\n' |
| 740 | 'precedence chain depends on which descriptor methods ' |
| 741 | 'were defined and\n' |
| 742 | 'how they were called.\n' |
| 743 | '\n' |
| 744 | 'The starting point for descriptor invocation is a ' |
| 745 | 'binding, "a.x". How\n' |
| 746 | 'the arguments are assembled depends on "a":\n' |
| 747 | '\n' |
| 748 | 'Direct Call\n' |
| 749 | ' The simplest and least common call is when user code ' |
| 750 | 'directly\n' |
| 751 | ' invokes a descriptor method: "x.__get__(a)".\n' |
| 752 | '\n' |
| 753 | 'Instance Binding\n' |
| 754 | ' If binding to an object instance, "a.x" is ' |
| 755 | 'transformed into the\n' |
| 756 | ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' |
| 757 | '\n' |
| 758 | 'Class Binding\n' |
| 759 | ' If binding to a class, "A.x" is transformed into the ' |
| 760 | 'call:\n' |
| 761 | ' "A.__dict__[\'x\'].__get__(None, A)".\n' |
| 762 | '\n' |
| 763 | 'Super Binding\n' |
| 764 | ' If "a" is an instance of "super", then the binding ' |
| 765 | '"super(B,\n' |
| 766 | ' obj).m()" searches "obj.__class__.__mro__" for the ' |
| 767 | 'base class "A"\n' |
| 768 | ' immediately preceding "B" and then invokes the ' |
| 769 | 'descriptor with the\n' |
| 770 | ' call: "A.__dict__[\'m\'].__get__(obj, ' |
| 771 | 'obj.__class__)".\n' |
| 772 | '\n' |
| 773 | 'For instance bindings, the precedence of descriptor ' |
| 774 | 'invocation depends\n' |
| 775 | 'on the which descriptor methods are defined. A ' |
| 776 | 'descriptor can define\n' |
| 777 | 'any combination of "__get__()", "__set__()" and ' |
| 778 | '"__delete__()". If it\n' |
| 779 | 'does not define "__get__()", then accessing the ' |
| 780 | 'attribute will return\n' |
| 781 | 'the descriptor object itself unless there is a value in ' |
| 782 | "the object's\n" |
| 783 | 'instance dictionary. If the descriptor defines ' |
| 784 | '"__set__()" and/or\n' |
| 785 | '"__delete__()", it is a data descriptor; if it defines ' |
| 786 | 'neither, it is\n' |
| 787 | 'a non-data descriptor. Normally, data descriptors ' |
| 788 | 'define both\n' |
| 789 | '"__get__()" and "__set__()", while non-data descriptors ' |
| 790 | 'have just the\n' |
| 791 | '"__get__()" method. Data descriptors with "__set__()" ' |
| 792 | 'and "__get__()"\n' |
| 793 | 'defined always override a redefinition in an instance ' |
| 794 | 'dictionary. In\n' |
| 795 | 'contrast, non-data descriptors can be overridden by ' |
| 796 | 'instances.\n' |
| 797 | '\n' |
| 798 | 'Python methods (including "staticmethod()" and ' |
| 799 | '"classmethod()") are\n' |
| 800 | 'implemented as non-data descriptors. Accordingly, ' |
| 801 | 'instances can\n' |
| 802 | 'redefine and override methods. This allows individual ' |
| 803 | 'instances to\n' |
| 804 | 'acquire behaviors that differ from other instances of ' |
| 805 | 'the same class.\n' |
| 806 | '\n' |
| 807 | 'The "property()" function is implemented as a data ' |
| 808 | 'descriptor.\n' |
| 809 | 'Accordingly, instances cannot override the behavior of a ' |
| 810 | 'property.\n' |
| 811 | '\n' |
| 812 | '\n' |
| 813 | '__slots__\n' |
| 814 | '=========\n' |
| 815 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 816 | '*__slots__* allow us to explicitly declare data members ' |
| 817 | '(like\n' |
| 818 | 'properties) and deny the creation of *__dict__* and ' |
| 819 | '*__weakref__*\n' |
| 820 | '(unless explicitly declared in *__slots__* or available ' |
| 821 | 'in a parent.)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 822 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 823 | 'The space saved over using *__dict__* can be ' |
| 824 | 'significant.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 825 | '\n' |
| 826 | 'object.__slots__\n' |
| 827 | '\n' |
| 828 | ' This class variable can be assigned a string, ' |
| 829 | 'iterable, or sequence\n' |
| 830 | ' of strings with variable names used by instances. ' |
| 831 | '*__slots__*\n' |
| 832 | ' reserves space for the declared variables and ' |
| 833 | 'prevents the\n' |
| 834 | ' automatic creation of *__dict__* and *__weakref__* ' |
| 835 | 'for each\n' |
| 836 | ' instance.\n' |
| 837 | '\n' |
| 838 | '\n' |
| 839 | 'Notes on using *__slots__*\n' |
| 840 | '--------------------------\n' |
| 841 | '\n' |
| 842 | '* When inheriting from a class without *__slots__*, the ' |
| 843 | '*__dict__*\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 844 | ' and *__weakref__* attribute of the instances will ' |
| 845 | 'always be\n' |
| 846 | ' accessible.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 847 | '\n' |
| 848 | '* Without a *__dict__* variable, instances cannot be ' |
| 849 | 'assigned new\n' |
| 850 | ' variables not listed in the *__slots__* definition. ' |
| 851 | 'Attempts to\n' |
| 852 | ' assign to an unlisted variable name raises ' |
| 853 | '"AttributeError". If\n' |
| 854 | ' dynamic assignment of new variables is desired, then ' |
| 855 | 'add\n' |
| 856 | ' "\'__dict__\'" to the sequence of strings in the ' |
| 857 | '*__slots__*\n' |
| 858 | ' declaration.\n' |
| 859 | '\n' |
| 860 | '* Without a *__weakref__* variable for each instance, ' |
| 861 | 'classes\n' |
| 862 | ' defining *__slots__* do not support weak references to ' |
| 863 | 'its\n' |
| 864 | ' instances. If weak reference support is needed, then ' |
| 865 | 'add\n' |
| 866 | ' "\'__weakref__\'" to the sequence of strings in the ' |
| 867 | '*__slots__*\n' |
| 868 | ' declaration.\n' |
| 869 | '\n' |
| 870 | '* *__slots__* are implemented at the class level by ' |
| 871 | 'creating\n' |
| 872 | ' descriptors (Implementing Descriptors) for each ' |
| 873 | 'variable name. As a\n' |
| 874 | ' result, class attributes cannot be used to set default ' |
| 875 | 'values for\n' |
| 876 | ' instance variables defined by *__slots__*; otherwise, ' |
| 877 | 'the class\n' |
| 878 | ' attribute would overwrite the descriptor assignment.\n' |
| 879 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 880 | '* The action of a *__slots__* declaration is not limited ' |
| 881 | 'to the\n' |
| 882 | ' class where it is defined. *__slots__* declared in ' |
| 883 | 'parents are\n' |
| 884 | ' available in child classes. However, child subclasses ' |
| 885 | 'will get a\n' |
| 886 | ' *__dict__* and *__weakref__* unless they also define ' |
| 887 | '*__slots__*\n' |
| 888 | ' (which should only contain names of any *additional* ' |
| 889 | 'slots).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 890 | '\n' |
| 891 | '* If a class defines a slot also defined in a base ' |
| 892 | 'class, the\n' |
| 893 | ' instance variable defined by the base class slot is ' |
| 894 | 'inaccessible\n' |
| 895 | ' (except by retrieving its descriptor directly from the ' |
| 896 | 'base class).\n' |
| 897 | ' This renders the meaning of the program undefined. In ' |
| 898 | 'the future, a\n' |
| 899 | ' check may be added to prevent this.\n' |
| 900 | '\n' |
| 901 | '* Nonempty *__slots__* does not work for classes derived ' |
| 902 | 'from\n' |
| 903 | ' "variable-length" built-in types such as "int", ' |
| 904 | '"bytes" and "tuple".\n' |
| 905 | '\n' |
| 906 | '* Any non-string iterable may be assigned to ' |
| 907 | '*__slots__*. Mappings\n' |
| 908 | ' may also be used; however, in the future, special ' |
| 909 | 'meaning may be\n' |
| 910 | ' assigned to the values corresponding to each key.\n' |
| 911 | '\n' |
| 912 | '* *__class__* assignment works only if both classes have ' |
| 913 | 'the same\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 914 | ' *__slots__*.\n' |
| 915 | '\n' |
| 916 | '* Multiple inheritance with multiple slotted parent ' |
| 917 | 'classes can be\n' |
| 918 | ' used, but only one parent is allowed to have ' |
| 919 | 'attributes created by\n' |
| 920 | ' slots (the other bases must have empty slot layouts) - ' |
| 921 | 'violations\n' |
| 922 | ' raise "TypeError".\n', |
| 923 | 'attribute-references': 'Attribute references\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 924 | '********************\n' |
| 925 | '\n' |
| 926 | 'An attribute reference is a primary followed by a ' |
| 927 | 'period and a name:\n' |
| 928 | '\n' |
| 929 | ' attributeref ::= primary "." identifier\n' |
| 930 | '\n' |
| 931 | 'The primary must evaluate to an object of a type ' |
| 932 | 'that supports\n' |
| 933 | 'attribute references, which most objects do. This ' |
| 934 | 'object is then\n' |
| 935 | 'asked to produce the attribute whose name is the ' |
| 936 | 'identifier. This\n' |
| 937 | 'production can be customized by overriding the ' |
| 938 | '"__getattr__()" method.\n' |
| 939 | 'If this attribute is not available, the exception ' |
| 940 | '"AttributeError" is\n' |
| 941 | 'raised. Otherwise, the type and value of the object ' |
| 942 | 'produced is\n' |
| 943 | 'determined by the object. Multiple evaluations of ' |
| 944 | 'the same attribute\n' |
| 945 | 'reference may yield different objects.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 946 | 'augassign': 'Augmented assignment statements\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 947 | '*******************************\n' |
| 948 | '\n' |
| 949 | 'Augmented assignment is the combination, in a single statement, ' |
| 950 | 'of a\n' |
| 951 | 'binary operation and an assignment statement:\n' |
| 952 | '\n' |
| 953 | ' augmented_assignment_stmt ::= augtarget augop ' |
| 954 | '(expression_list | yield_expression)\n' |
| 955 | ' augtarget ::= identifier | attributeref | ' |
| 956 | 'subscription | slicing\n' |
| 957 | ' augop ::= "+=" | "-=" | "*=" | "@=" | ' |
| 958 | '"/=" | "//=" | "%=" | "**="\n' |
| 959 | ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' |
| 960 | '\n' |
| 961 | '(See section Primaries for the syntax definitions of the last ' |
| 962 | 'three\n' |
| 963 | 'symbols.)\n' |
| 964 | '\n' |
| 965 | 'An augmented assignment evaluates the target (which, unlike ' |
| 966 | 'normal\n' |
| 967 | 'assignment statements, cannot be an unpacking) and the ' |
| 968 | 'expression\n' |
| 969 | 'list, performs the binary operation specific to the type of ' |
| 970 | 'assignment\n' |
| 971 | 'on the two operands, and assigns the result to the original ' |
| 972 | 'target.\n' |
| 973 | 'The target is only evaluated once.\n' |
| 974 | '\n' |
| 975 | 'An augmented assignment expression like "x += 1" can be ' |
| 976 | 'rewritten as\n' |
| 977 | '"x = x + 1" to achieve a similar, but not exactly equal effect. ' |
| 978 | 'In the\n' |
| 979 | 'augmented version, "x" is only evaluated once. Also, when ' |
| 980 | 'possible,\n' |
| 981 | 'the actual operation is performed *in-place*, meaning that ' |
| 982 | 'rather than\n' |
| 983 | 'creating a new object and assigning that to the target, the old ' |
| 984 | 'object\n' |
| 985 | 'is modified instead.\n' |
| 986 | '\n' |
| 987 | 'Unlike normal assignments, augmented assignments evaluate the ' |
| 988 | 'left-\n' |
| 989 | 'hand side *before* evaluating the right-hand side. For ' |
| 990 | 'example, "a[i]\n' |
| 991 | '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' |
| 992 | 'performs\n' |
| 993 | 'the addition, and lastly, it writes the result back to "a[i]".\n' |
| 994 | '\n' |
| 995 | 'With the exception of assigning to tuples and multiple targets ' |
| 996 | 'in a\n' |
| 997 | 'single statement, the assignment done by augmented assignment\n' |
| 998 | 'statements is handled the same way as normal assignments. ' |
| 999 | 'Similarly,\n' |
| 1000 | 'with the exception of the possible *in-place* behavior, the ' |
| 1001 | 'binary\n' |
| 1002 | 'operation performed by augmented assignment is the same as the ' |
| 1003 | 'normal\n' |
| 1004 | 'binary operations.\n' |
| 1005 | '\n' |
| 1006 | 'For targets which are attribute references, the same caveat ' |
| 1007 | 'about\n' |
| 1008 | 'class and instance attributes applies as for regular ' |
| 1009 | 'assignments.\n', |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 1010 | 'await': 'Await expression\n' |
| 1011 | '****************\n' |
| 1012 | '\n' |
| 1013 | 'Suspend the execution of *coroutine* on an *awaitable* object. Can\n' |
| 1014 | 'only be used inside a *coroutine function*.\n' |
| 1015 | '\n' |
| 1016 | ' await_expr ::= "await" primary\n' |
| 1017 | '\n' |
| 1018 | 'New in version 3.5.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1019 | 'binary': 'Binary arithmetic operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1020 | '****************************\n' |
| 1021 | '\n' |
| 1022 | 'The binary arithmetic operations have the conventional priority\n' |
| 1023 | 'levels. Note that some of these operations also apply to certain ' |
| 1024 | 'non-\n' |
| 1025 | 'numeric types. Apart from the power operator, there are only two\n' |
| 1026 | 'levels, one for multiplicative operators and one for additive\n' |
| 1027 | 'operators:\n' |
| 1028 | '\n' |
| 1029 | ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n' |
| 1030 | ' m_expr "//" u_expr| m_expr "/" u_expr |\n' |
| 1031 | ' m_expr "%" u_expr\n' |
| 1032 | ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' |
| 1033 | '\n' |
| 1034 | 'The "*" (multiplication) operator yields the product of its ' |
| 1035 | 'arguments.\n' |
| 1036 | 'The arguments must either both be numbers, or one argument must be ' |
| 1037 | 'an\n' |
| 1038 | 'integer and the other must be a sequence. In the former case, the\n' |
| 1039 | 'numbers are converted to a common type and then multiplied ' |
| 1040 | 'together.\n' |
| 1041 | 'In the latter case, sequence repetition is performed; a negative\n' |
| 1042 | 'repetition factor yields an empty sequence.\n' |
| 1043 | '\n' |
| 1044 | 'The "@" (at) operator is intended to be used for matrix\n' |
| 1045 | 'multiplication. No builtin Python types implement this operator.\n' |
| 1046 | '\n' |
| 1047 | 'New in version 3.5.\n' |
| 1048 | '\n' |
| 1049 | 'The "/" (division) and "//" (floor division) operators yield the\n' |
| 1050 | 'quotient of their arguments. The numeric arguments are first\n' |
| 1051 | 'converted to a common type. Division of integers yields a float, ' |
| 1052 | 'while\n' |
| 1053 | 'floor division of integers results in an integer; the result is ' |
| 1054 | 'that\n' |
| 1055 | "of mathematical division with the 'floor' function applied to the\n" |
| 1056 | 'result. Division by zero raises the "ZeroDivisionError" ' |
| 1057 | 'exception.\n' |
| 1058 | '\n' |
| 1059 | 'The "%" (modulo) operator yields the remainder from the division ' |
| 1060 | 'of\n' |
| 1061 | 'the first argument by the second. The numeric arguments are ' |
| 1062 | 'first\n' |
| 1063 | 'converted to a common type. A zero right argument raises the\n' |
| 1064 | '"ZeroDivisionError" exception. The arguments may be floating ' |
| 1065 | 'point\n' |
| 1066 | 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals ' |
| 1067 | '"4*0.7 +\n' |
| 1068 | '0.34".) The modulo operator always yields a result with the same ' |
| 1069 | 'sign\n' |
| 1070 | 'as its second operand (or zero); the absolute value of the result ' |
| 1071 | 'is\n' |
| 1072 | 'strictly smaller than the absolute value of the second operand ' |
| 1073 | '[1].\n' |
| 1074 | '\n' |
| 1075 | 'The floor division and modulo operators are connected by the ' |
| 1076 | 'following\n' |
| 1077 | 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are ' |
| 1078 | 'also\n' |
| 1079 | 'connected with the built-in function "divmod()": "divmod(x, y) ==\n' |
| 1080 | '(x//y, x%y)". [2].\n' |
| 1081 | '\n' |
| 1082 | 'In addition to performing the modulo operation on numbers, the ' |
| 1083 | '"%"\n' |
| 1084 | 'operator is also overloaded by string objects to perform ' |
| 1085 | 'old-style\n' |
| 1086 | 'string formatting (also known as interpolation). The syntax for\n' |
| 1087 | 'string formatting is described in the Python Library Reference,\n' |
| 1088 | 'section printf-style String Formatting.\n' |
| 1089 | '\n' |
| 1090 | 'The floor division operator, the modulo operator, and the ' |
| 1091 | '"divmod()"\n' |
| 1092 | 'function are not defined for complex numbers. Instead, convert to ' |
| 1093 | 'a\n' |
| 1094 | 'floating point number using the "abs()" function if appropriate.\n' |
| 1095 | '\n' |
| 1096 | 'The "+" (addition) operator yields the sum of its arguments. The\n' |
| 1097 | 'arguments must either both be numbers or both be sequences of the ' |
| 1098 | 'same\n' |
| 1099 | 'type. In the former case, the numbers are converted to a common ' |
| 1100 | 'type\n' |
| 1101 | 'and then added together. In the latter case, the sequences are\n' |
| 1102 | 'concatenated.\n' |
| 1103 | '\n' |
| 1104 | 'The "-" (subtraction) operator yields the difference of its ' |
| 1105 | 'arguments.\n' |
| 1106 | 'The numeric arguments are first converted to a common type.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1107 | 'bitwise': 'Binary bitwise operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1108 | '*************************\n' |
| 1109 | '\n' |
| 1110 | 'Each of the three bitwise operations has a different priority ' |
| 1111 | 'level:\n' |
| 1112 | '\n' |
| 1113 | ' and_expr ::= shift_expr | and_expr "&" shift_expr\n' |
| 1114 | ' xor_expr ::= and_expr | xor_expr "^" and_expr\n' |
| 1115 | ' or_expr ::= xor_expr | or_expr "|" xor_expr\n' |
| 1116 | '\n' |
| 1117 | 'The "&" operator yields the bitwise AND of its arguments, which ' |
| 1118 | 'must\n' |
| 1119 | 'be integers.\n' |
| 1120 | '\n' |
| 1121 | 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' |
| 1122 | 'arguments, which must be integers.\n' |
| 1123 | '\n' |
| 1124 | 'The "|" operator yields the bitwise (inclusive) OR of its ' |
| 1125 | 'arguments,\n' |
| 1126 | 'which must be integers.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1127 | 'bltin-code-objects': 'Code Objects\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1128 | '************\n' |
| 1129 | '\n' |
| 1130 | 'Code objects are used by the implementation to ' |
| 1131 | 'represent "pseudo-\n' |
| 1132 | 'compiled" executable Python code such as a function ' |
| 1133 | 'body. They differ\n' |
| 1134 | "from function objects because they don't contain a " |
| 1135 | 'reference to their\n' |
| 1136 | 'global execution environment. Code objects are ' |
| 1137 | 'returned by the built-\n' |
| 1138 | 'in "compile()" function and can be extracted from ' |
| 1139 | 'function objects\n' |
| 1140 | 'through their "__code__" attribute. See also the ' |
| 1141 | '"code" module.\n' |
| 1142 | '\n' |
| 1143 | 'A code object can be executed or evaluated by passing ' |
| 1144 | 'it (instead of a\n' |
| 1145 | 'source string) to the "exec()" or "eval()" built-in ' |
| 1146 | 'functions.\n' |
| 1147 | '\n' |
| 1148 | 'See The standard type hierarchy for more ' |
| 1149 | 'information.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1150 | 'bltin-ellipsis-object': 'The Ellipsis Object\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1151 | '*******************\n' |
| 1152 | '\n' |
| 1153 | 'This object is commonly used by slicing (see ' |
| 1154 | 'Slicings). It supports\n' |
| 1155 | 'no special operations. There is exactly one ' |
| 1156 | 'ellipsis object, named\n' |
| 1157 | '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' |
| 1158 | 'produces the\n' |
| 1159 | '"Ellipsis" singleton.\n' |
| 1160 | '\n' |
| 1161 | 'It is written as "Ellipsis" or "...".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1162 | 'bltin-null-object': 'The Null Object\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1163 | '***************\n' |
| 1164 | '\n' |
| 1165 | "This object is returned by functions that don't " |
| 1166 | 'explicitly return a\n' |
| 1167 | 'value. It supports no special operations. There is ' |
| 1168 | 'exactly one null\n' |
| 1169 | 'object, named "None" (a built-in name). "type(None)()" ' |
| 1170 | 'produces the\n' |
| 1171 | 'same singleton.\n' |
| 1172 | '\n' |
| 1173 | 'It is written as "None".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1174 | 'bltin-type-objects': 'Type Objects\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1175 | '************\n' |
| 1176 | '\n' |
| 1177 | 'Type objects represent the various object types. An ' |
| 1178 | "object's type is\n" |
| 1179 | 'accessed by the built-in function "type()". There are ' |
| 1180 | 'no special\n' |
| 1181 | 'operations on types. The standard module "types" ' |
| 1182 | 'defines names for\n' |
| 1183 | 'all standard built-in types.\n' |
| 1184 | '\n' |
| 1185 | 'Types are written like this: "<class \'int\'>".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1186 | 'booleans': 'Boolean operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1187 | '******************\n' |
| 1188 | '\n' |
| 1189 | ' or_test ::= and_test | or_test "or" and_test\n' |
| 1190 | ' and_test ::= not_test | and_test "and" not_test\n' |
| 1191 | ' not_test ::= comparison | "not" not_test\n' |
| 1192 | '\n' |
| 1193 | 'In the context of Boolean operations, and also when expressions ' |
| 1194 | 'are\n' |
| 1195 | 'used by control flow statements, the following values are ' |
| 1196 | 'interpreted\n' |
| 1197 | 'as false: "False", "None", numeric zero of all types, and empty\n' |
| 1198 | 'strings and containers (including strings, tuples, lists,\n' |
| 1199 | 'dictionaries, sets and frozensets). All other values are ' |
| 1200 | 'interpreted\n' |
| 1201 | 'as true. User-defined objects can customize their truth value ' |
| 1202 | 'by\n' |
| 1203 | 'providing a "__bool__()" method.\n' |
| 1204 | '\n' |
| 1205 | 'The operator "not" yields "True" if its argument is false, ' |
| 1206 | '"False"\n' |
| 1207 | 'otherwise.\n' |
| 1208 | '\n' |
| 1209 | 'The expression "x and y" first evaluates *x*; if *x* is false, ' |
| 1210 | 'its\n' |
| 1211 | 'value is returned; otherwise, *y* is evaluated and the resulting ' |
| 1212 | 'value\n' |
| 1213 | 'is returned.\n' |
| 1214 | '\n' |
| 1215 | 'The expression "x or y" first evaluates *x*; if *x* is true, its ' |
| 1216 | 'value\n' |
| 1217 | 'is returned; otherwise, *y* is evaluated and the resulting value ' |
| 1218 | 'is\n' |
| 1219 | 'returned.\n' |
| 1220 | '\n' |
| 1221 | '(Note that neither "and" nor "or" restrict the value and type ' |
| 1222 | 'they\n' |
| 1223 | 'return to "False" and "True", but rather return the last ' |
| 1224 | 'evaluated\n' |
| 1225 | 'argument. This is sometimes useful, e.g., if "s" is a string ' |
| 1226 | 'that\n' |
| 1227 | 'should be replaced by a default value if it is empty, the ' |
| 1228 | 'expression\n' |
| 1229 | '"s or \'foo\'" yields the desired value. Because "not" has to ' |
| 1230 | 'create a\n' |
| 1231 | 'new value, it returns a boolean value regardless of the type of ' |
| 1232 | 'its\n' |
| 1233 | 'argument (for example, "not \'foo\'" produces "False" rather ' |
| 1234 | 'than "\'\'".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1235 | 'break': 'The "break" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1236 | '*********************\n' |
| 1237 | '\n' |
| 1238 | ' break_stmt ::= "break"\n' |
| 1239 | '\n' |
| 1240 | '"break" may only occur syntactically nested in a "for" or "while"\n' |
| 1241 | 'loop, but not nested in a function or class definition within that\n' |
| 1242 | 'loop.\n' |
| 1243 | '\n' |
| 1244 | 'It terminates the nearest enclosing loop, skipping the optional ' |
| 1245 | '"else"\n' |
| 1246 | 'clause if the loop has one.\n' |
| 1247 | '\n' |
| 1248 | 'If a "for" loop is terminated by "break", the loop control target\n' |
| 1249 | 'keeps its current value.\n' |
| 1250 | '\n' |
| 1251 | 'When "break" passes control out of a "try" statement with a ' |
| 1252 | '"finally"\n' |
| 1253 | 'clause, that "finally" clause is executed before really leaving ' |
| 1254 | 'the\n' |
| 1255 | 'loop.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1256 | 'callable-types': 'Emulating callable objects\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1257 | '**************************\n' |
| 1258 | '\n' |
| 1259 | 'object.__call__(self[, args...])\n' |
| 1260 | '\n' |
| 1261 | ' Called when the instance is "called" as a function; if ' |
| 1262 | 'this method\n' |
| 1263 | ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' |
| 1264 | ' "x.__call__(arg1, arg2, ...)".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1265 | 'calls': 'Calls\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1266 | '*****\n' |
| 1267 | '\n' |
| 1268 | 'A call calls a callable object (e.g., a *function*) with a ' |
| 1269 | 'possibly\n' |
| 1270 | 'empty series of *arguments*:\n' |
| 1271 | '\n' |
| 1272 | ' call ::= primary "(" [argument_list [","] | ' |
| 1273 | 'comprehension] ")"\n' |
| 1274 | ' argument_list ::= positional_arguments ["," ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1275 | 'starred_and_keywords]\n' |
| 1276 | ' ["," keywords_arguments]\n' |
| 1277 | ' | starred_and_keywords ["," ' |
| 1278 | 'keywords_arguments]\n' |
| 1279 | ' | keywords_arguments\n' |
| 1280 | ' positional_arguments ::= ["*"] expression ("," ["*"] ' |
| 1281 | 'expression)*\n' |
| 1282 | ' starred_and_keywords ::= ("*" expression | keyword_item)\n' |
| 1283 | ' ("," "*" expression | "," ' |
| 1284 | 'keyword_item)*\n' |
| 1285 | ' keywords_arguments ::= (keyword_item | "**" expression)\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1286 | ' ("," keyword_item | "," "**" ' |
| 1287 | 'expression)*\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1288 | ' keyword_item ::= identifier "=" expression\n' |
| 1289 | '\n' |
| 1290 | 'An optional trailing comma may be present after the positional and\n' |
| 1291 | 'keyword arguments but does not affect the semantics.\n' |
| 1292 | '\n' |
| 1293 | 'The primary must evaluate to a callable object (user-defined\n' |
| 1294 | 'functions, built-in functions, methods of built-in objects, class\n' |
| 1295 | 'objects, methods of class instances, and all objects having a\n' |
| 1296 | '"__call__()" method are callable). All argument expressions are\n' |
| 1297 | 'evaluated before the call is attempted. Please refer to section\n' |
| 1298 | 'Function definitions for the syntax of formal *parameter* lists.\n' |
| 1299 | '\n' |
| 1300 | 'If keyword arguments are present, they are first converted to\n' |
| 1301 | 'positional arguments, as follows. First, a list of unfilled slots ' |
| 1302 | 'is\n' |
| 1303 | 'created for the formal parameters. If there are N positional\n' |
| 1304 | 'arguments, they are placed in the first N slots. Next, for each\n' |
| 1305 | 'keyword argument, the identifier is used to determine the\n' |
| 1306 | 'corresponding slot (if the identifier is the same as the first ' |
| 1307 | 'formal\n' |
| 1308 | 'parameter name, the first slot is used, and so on). If the slot ' |
| 1309 | 'is\n' |
| 1310 | 'already filled, a "TypeError" exception is raised. Otherwise, the\n' |
| 1311 | 'value of the argument is placed in the slot, filling it (even if ' |
| 1312 | 'the\n' |
| 1313 | 'expression is "None", it fills the slot). When all arguments have\n' |
| 1314 | 'been processed, the slots that are still unfilled are filled with ' |
| 1315 | 'the\n' |
| 1316 | 'corresponding default value from the function definition. ' |
| 1317 | '(Default\n' |
| 1318 | 'values are calculated, once, when the function is defined; thus, a\n' |
| 1319 | 'mutable object such as a list or dictionary used as default value ' |
| 1320 | 'will\n' |
| 1321 | "be shared by all calls that don't specify an argument value for " |
| 1322 | 'the\n' |
| 1323 | 'corresponding slot; this should usually be avoided.) If there are ' |
| 1324 | 'any\n' |
| 1325 | 'unfilled slots for which no default value is specified, a ' |
| 1326 | '"TypeError"\n' |
| 1327 | 'exception is raised. Otherwise, the list of filled slots is used ' |
| 1328 | 'as\n' |
| 1329 | 'the argument list for the call.\n' |
| 1330 | '\n' |
| 1331 | '**CPython implementation detail:** An implementation may provide\n' |
| 1332 | 'built-in functions whose positional parameters do not have names, ' |
| 1333 | 'even\n' |
| 1334 | "if they are 'named' for the purpose of documentation, and which\n" |
| 1335 | 'therefore cannot be supplied by keyword. In CPython, this is the ' |
| 1336 | 'case\n' |
| 1337 | 'for functions implemented in C that use "PyArg_ParseTuple()" to ' |
| 1338 | 'parse\n' |
| 1339 | 'their arguments.\n' |
| 1340 | '\n' |
| 1341 | 'If there are more positional arguments than there are formal ' |
| 1342 | 'parameter\n' |
| 1343 | 'slots, a "TypeError" exception is raised, unless a formal ' |
| 1344 | 'parameter\n' |
| 1345 | 'using the syntax "*identifier" is present; in this case, that ' |
| 1346 | 'formal\n' |
| 1347 | 'parameter receives a tuple containing the excess positional ' |
| 1348 | 'arguments\n' |
| 1349 | '(or an empty tuple if there were no excess positional arguments).\n' |
| 1350 | '\n' |
| 1351 | 'If any keyword argument does not correspond to a formal parameter\n' |
| 1352 | 'name, a "TypeError" exception is raised, unless a formal parameter\n' |
| 1353 | 'using the syntax "**identifier" is present; in this case, that ' |
| 1354 | 'formal\n' |
| 1355 | 'parameter receives a dictionary containing the excess keyword\n' |
| 1356 | 'arguments (using the keywords as keys and the argument values as\n' |
| 1357 | 'corresponding values), or a (new) empty dictionary if there were ' |
| 1358 | 'no\n' |
| 1359 | 'excess keyword arguments.\n' |
| 1360 | '\n' |
| 1361 | 'If the syntax "*expression" appears in the function call, ' |
| 1362 | '"expression"\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1363 | 'must evaluate to an *iterable*. Elements from these iterables are\n' |
| 1364 | 'treated as if they were additional positional arguments. For the ' |
| 1365 | 'call\n' |
| 1366 | '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, ...,\n' |
| 1367 | '*yM*, this is equivalent to a call with M+4 positional arguments ' |
| 1368 | '*x1*,\n' |
| 1369 | '*x2*, *y1*, ..., *yM*, *x3*, *x4*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1370 | '\n' |
| 1371 | 'A consequence of this is that although the "*expression" syntax ' |
| 1372 | 'may\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1373 | 'appear *after* explicit keyword arguments, it is processed ' |
| 1374 | '*before*\n' |
| 1375 | 'the keyword arguments (and any "**expression" arguments -- see ' |
| 1376 | 'below).\n' |
| 1377 | 'So:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1378 | '\n' |
| 1379 | ' >>> def f(a, b):\n' |
| 1380 | ' ... print(a, b)\n' |
| 1381 | ' ...\n' |
| 1382 | ' >>> f(b=1, *(2,))\n' |
| 1383 | ' 2 1\n' |
| 1384 | ' >>> f(a=1, *(2,))\n' |
| 1385 | ' Traceback (most recent call last):\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1386 | ' File "<stdin>", line 1, in <module>\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1387 | " TypeError: f() got multiple values for keyword argument 'a'\n" |
| 1388 | ' >>> f(1, *(2,))\n' |
| 1389 | ' 1 2\n' |
| 1390 | '\n' |
| 1391 | 'It is unusual for both keyword arguments and the "*expression" ' |
| 1392 | 'syntax\n' |
| 1393 | 'to be used in the same call, so in practice this confusion does ' |
| 1394 | 'not\n' |
| 1395 | 'arise.\n' |
| 1396 | '\n' |
| 1397 | 'If the syntax "**expression" appears in the function call,\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1398 | '"expression" must evaluate to a *mapping*, the contents of which ' |
| 1399 | 'are\n' |
| 1400 | 'treated as additional keyword arguments. If a keyword is already\n' |
| 1401 | 'present (as an explicit keyword argument, or from another ' |
| 1402 | 'unpacking),\n' |
| 1403 | 'a "TypeError" exception is raised.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1404 | '\n' |
| 1405 | 'Formal parameters using the syntax "*identifier" or "**identifier"\n' |
| 1406 | 'cannot be used as positional argument slots or as keyword argument\n' |
| 1407 | 'names.\n' |
| 1408 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1409 | 'Changed in version 3.5: Function calls accept any number of "*" ' |
| 1410 | 'and\n' |
| 1411 | '"**" unpackings, positional arguments may follow iterable ' |
| 1412 | 'unpackings\n' |
| 1413 | '("*"), and keyword arguments may follow dictionary unpackings ' |
| 1414 | '("**").\n' |
| 1415 | 'Originally proposed by **PEP 448**.\n' |
| 1416 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1417 | 'A call always returns some value, possibly "None", unless it raises ' |
| 1418 | 'an\n' |
| 1419 | 'exception. How this value is computed depends on the type of the\n' |
| 1420 | 'callable object.\n' |
| 1421 | '\n' |
| 1422 | 'If it is---\n' |
| 1423 | '\n' |
| 1424 | 'a user-defined function:\n' |
| 1425 | ' The code block for the function is executed, passing it the\n' |
| 1426 | ' argument list. The first thing the code block will do is bind ' |
| 1427 | 'the\n' |
| 1428 | ' formal parameters to the arguments; this is described in ' |
| 1429 | 'section\n' |
| 1430 | ' Function definitions. When the code block executes a "return"\n' |
| 1431 | ' statement, this specifies the return value of the function ' |
| 1432 | 'call.\n' |
| 1433 | '\n' |
| 1434 | 'a built-in function or method:\n' |
| 1435 | ' The result is up to the interpreter; see Built-in Functions for ' |
| 1436 | 'the\n' |
| 1437 | ' descriptions of built-in functions and methods.\n' |
| 1438 | '\n' |
| 1439 | 'a class object:\n' |
| 1440 | ' A new instance of that class is returned.\n' |
| 1441 | '\n' |
| 1442 | 'a class instance method:\n' |
| 1443 | ' The corresponding user-defined function is called, with an ' |
| 1444 | 'argument\n' |
| 1445 | ' list that is one longer than the argument list of the call: the\n' |
| 1446 | ' instance becomes the first argument.\n' |
| 1447 | '\n' |
| 1448 | 'a class instance:\n' |
| 1449 | ' The class must define a "__call__()" method; the effect is then ' |
| 1450 | 'the\n' |
| 1451 | ' same as if that method was called.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1452 | 'class': 'Class definitions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1453 | '*****************\n' |
| 1454 | '\n' |
| 1455 | 'A class definition defines a class object (see section The ' |
| 1456 | 'standard\n' |
| 1457 | 'type hierarchy):\n' |
| 1458 | '\n' |
| 1459 | ' classdef ::= [decorators] "class" classname [inheritance] ":" ' |
| 1460 | 'suite\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 1461 | ' inheritance ::= "(" [argument_list] ")"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1462 | ' classname ::= identifier\n' |
| 1463 | '\n' |
| 1464 | 'A class definition is an executable statement. The inheritance ' |
| 1465 | 'list\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 1466 | 'usually gives a list of base classes (see Metaclasses for more\n' |
| 1467 | 'advanced uses), so each item in the list should evaluate to a ' |
| 1468 | 'class\n' |
| 1469 | 'object which allows subclassing. Classes without an inheritance ' |
| 1470 | 'list\n' |
| 1471 | 'inherit, by default, from the base class "object"; hence,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1472 | '\n' |
| 1473 | ' class Foo:\n' |
| 1474 | ' pass\n' |
| 1475 | '\n' |
| 1476 | 'is equivalent to\n' |
| 1477 | '\n' |
| 1478 | ' class Foo(object):\n' |
| 1479 | ' pass\n' |
| 1480 | '\n' |
| 1481 | "The class's suite is then executed in a new execution frame (see\n" |
| 1482 | 'Naming and binding), using a newly created local namespace and the\n' |
| 1483 | 'original global namespace. (Usually, the suite contains mostly\n' |
| 1484 | "function definitions.) When the class's suite finishes execution, " |
| 1485 | 'its\n' |
| 1486 | 'execution frame is discarded but its local namespace is saved. [4] ' |
| 1487 | 'A\n' |
| 1488 | 'class object is then created using the inheritance list for the ' |
| 1489 | 'base\n' |
| 1490 | 'classes and the saved local namespace for the attribute ' |
| 1491 | 'dictionary.\n' |
| 1492 | 'The class name is bound to this class object in the original local\n' |
| 1493 | 'namespace.\n' |
| 1494 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 1495 | 'The order in which attributes are defined in the class body is\n' |
| 1496 | 'preserved in the new class\'s "__dict__". Note that this is ' |
| 1497 | 'reliable\n' |
| 1498 | 'only right after the class is created and only for classes that ' |
| 1499 | 'were\n' |
| 1500 | 'defined using the definition syntax.\n' |
| 1501 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1502 | 'Class creation can be customized heavily using metaclasses.\n' |
| 1503 | '\n' |
| 1504 | 'Classes can also be decorated: just like when decorating ' |
| 1505 | 'functions,\n' |
| 1506 | '\n' |
| 1507 | ' @f1(arg)\n' |
| 1508 | ' @f2\n' |
| 1509 | ' class Foo: pass\n' |
| 1510 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 1511 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1512 | '\n' |
| 1513 | ' class Foo: pass\n' |
| 1514 | ' Foo = f1(arg)(f2(Foo))\n' |
| 1515 | '\n' |
| 1516 | 'The evaluation rules for the decorator expressions are the same as ' |
| 1517 | 'for\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 1518 | 'function decorators. The result is then bound to the class name.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1519 | '\n' |
| 1520 | "**Programmer's note:** Variables defined in the class definition " |
| 1521 | 'are\n' |
| 1522 | 'class attributes; they are shared by instances. Instance ' |
| 1523 | 'attributes\n' |
| 1524 | 'can be set in a method with "self.name = value". Both class and\n' |
| 1525 | 'instance attributes are accessible through the notation ' |
| 1526 | '""self.name"",\n' |
| 1527 | 'and an instance attribute hides a class attribute with the same ' |
| 1528 | 'name\n' |
| 1529 | 'when accessed in this way. Class attributes can be used as ' |
| 1530 | 'defaults\n' |
| 1531 | 'for instance attributes, but using mutable values there can lead ' |
| 1532 | 'to\n' |
| 1533 | 'unexpected results. Descriptors can be used to create instance\n' |
| 1534 | 'variables with different implementation details.\n' |
| 1535 | '\n' |
| 1536 | 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n' |
| 1537 | ' Class Decorators\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1538 | 'comparisons': 'Comparisons\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1539 | '***********\n' |
| 1540 | '\n' |
| 1541 | 'Unlike C, all comparison operations in Python have the same ' |
| 1542 | 'priority,\n' |
| 1543 | 'which is lower than that of any arithmetic, shifting or ' |
| 1544 | 'bitwise\n' |
| 1545 | 'operation. Also unlike C, expressions like "a < b < c" have ' |
| 1546 | 'the\n' |
| 1547 | 'interpretation that is conventional in mathematics:\n' |
| 1548 | '\n' |
| 1549 | ' comparison ::= or_expr ( comp_operator or_expr )*\n' |
| 1550 | ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' |
| 1551 | ' | "is" ["not"] | ["not"] "in"\n' |
| 1552 | '\n' |
| 1553 | 'Comparisons yield boolean values: "True" or "False".\n' |
| 1554 | '\n' |
| 1555 | 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" ' |
| 1556 | 'is\n' |
| 1557 | 'equivalent to "x < y and y <= z", except that "y" is ' |
| 1558 | 'evaluated only\n' |
| 1559 | 'once (but in both cases "z" is not evaluated at all when "x < ' |
| 1560 | 'y" is\n' |
| 1561 | 'found to be false).\n' |
| 1562 | '\n' |
| 1563 | 'Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and ' |
| 1564 | '*op1*,\n' |
| 1565 | '*op2*, ..., *opN* are comparison operators, then "a op1 b op2 ' |
| 1566 | 'c ... y\n' |
| 1567 | 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' |
| 1568 | 'z", except\n' |
| 1569 | 'that each expression is evaluated at most once.\n' |
| 1570 | '\n' |
| 1571 | 'Note that "a op1 b op2 c" doesn\'t imply any kind of ' |
| 1572 | 'comparison between\n' |
| 1573 | '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' |
| 1574 | '(though\n' |
| 1575 | 'perhaps not pretty).\n' |
| 1576 | '\n' |
| 1577 | '\n' |
| 1578 | 'Value comparisons\n' |
| 1579 | '=================\n' |
| 1580 | '\n' |
| 1581 | 'The operators "<", ">", "==", ">=", "<=", and "!=" compare ' |
| 1582 | 'the values\n' |
| 1583 | 'of two objects. The objects do not need to have the same ' |
| 1584 | 'type.\n' |
| 1585 | '\n' |
| 1586 | 'Chapter Objects, values and types states that objects have a ' |
| 1587 | 'value (in\n' |
| 1588 | 'addition to type and identity). The value of an object is a ' |
| 1589 | 'rather\n' |
| 1590 | 'abstract notion in Python: For example, there is no canonical ' |
| 1591 | 'access\n' |
| 1592 | "method for an object's value. Also, there is no requirement " |
| 1593 | 'that the\n' |
| 1594 | 'value of an object should be constructed in a particular way, ' |
| 1595 | 'e.g.\n' |
| 1596 | 'comprised of all its data attributes. Comparison operators ' |
| 1597 | 'implement a\n' |
| 1598 | 'particular notion of what the value of an object is. One can ' |
| 1599 | 'think of\n' |
| 1600 | 'them as defining the value of an object indirectly, by means ' |
| 1601 | 'of their\n' |
| 1602 | 'comparison implementation.\n' |
| 1603 | '\n' |
| 1604 | 'Because all types are (direct or indirect) subtypes of ' |
| 1605 | '"object", they\n' |
| 1606 | 'inherit the default comparison behavior from "object". Types ' |
| 1607 | 'can\n' |
| 1608 | 'customize their comparison behavior by implementing *rich ' |
| 1609 | 'comparison\n' |
| 1610 | 'methods* like "__lt__()", described in Basic customization.\n' |
| 1611 | '\n' |
| 1612 | 'The default behavior for equality comparison ("==" and "!=") ' |
| 1613 | 'is based\n' |
| 1614 | 'on the identity of the objects. Hence, equality comparison ' |
| 1615 | 'of\n' |
| 1616 | 'instances with the same identity results in equality, and ' |
| 1617 | 'equality\n' |
| 1618 | 'comparison of instances with different identities results in\n' |
| 1619 | 'inequality. A motivation for this default behavior is the ' |
| 1620 | 'desire that\n' |
| 1621 | 'all objects should be reflexive (i.e. "x is y" implies "x == ' |
| 1622 | 'y").\n' |
| 1623 | '\n' |
| 1624 | 'A default order comparison ("<", ">", "<=", and ">=") is not ' |
| 1625 | 'provided;\n' |
| 1626 | 'an attempt raises "TypeError". A motivation for this default ' |
| 1627 | 'behavior\n' |
| 1628 | 'is the lack of a similar invariant as for equality.\n' |
| 1629 | '\n' |
| 1630 | 'The behavior of the default equality comparison, that ' |
| 1631 | 'instances with\n' |
| 1632 | 'different identities are always unequal, may be in contrast ' |
| 1633 | 'to what\n' |
| 1634 | 'types will need that have a sensible definition of object ' |
| 1635 | 'value and\n' |
| 1636 | 'value-based equality. Such types will need to customize ' |
| 1637 | 'their\n' |
| 1638 | 'comparison behavior, and in fact, a number of built-in types ' |
| 1639 | 'have done\n' |
| 1640 | 'that.\n' |
| 1641 | '\n' |
| 1642 | 'The following list describes the comparison behavior of the ' |
| 1643 | 'most\n' |
| 1644 | 'important built-in types.\n' |
| 1645 | '\n' |
| 1646 | '* Numbers of built-in numeric types (Numeric Types --- int, ' |
| 1647 | 'float,\n' |
| 1648 | ' complex) and of the standard library types ' |
| 1649 | '"fractions.Fraction" and\n' |
| 1650 | ' "decimal.Decimal" can be compared within and across their ' |
| 1651 | 'types,\n' |
| 1652 | ' with the restriction that complex numbers do not support ' |
| 1653 | 'order\n' |
| 1654 | ' comparison. Within the limits of the types involved, they ' |
| 1655 | 'compare\n' |
| 1656 | ' mathematically (algorithmically) correct without loss of ' |
| 1657 | 'precision.\n' |
| 1658 | '\n' |
| 1659 | ' The not-a-number values "float(\'NaN\')" and ' |
| 1660 | '"Decimal(\'NaN\')" are\n' |
| 1661 | ' special. They are identical to themselves ("x is x" is ' |
| 1662 | 'true) but\n' |
| 1663 | ' are not equal to themselves ("x == x" is false). ' |
| 1664 | 'Additionally,\n' |
| 1665 | ' comparing any number to a not-a-number value will return ' |
| 1666 | '"False".\n' |
| 1667 | ' For example, both "3 < float(\'NaN\')" and "float(\'NaN\') ' |
| 1668 | '< 3" will\n' |
| 1669 | ' return "False".\n' |
| 1670 | '\n' |
| 1671 | '* Binary sequences (instances of "bytes" or "bytearray") can ' |
| 1672 | 'be\n' |
| 1673 | ' compared within and across their types. They compare\n' |
| 1674 | ' lexicographically using the numeric values of their ' |
| 1675 | 'elements.\n' |
| 1676 | '\n' |
| 1677 | '* Strings (instances of "str") compare lexicographically ' |
| 1678 | 'using the\n' |
| 1679 | ' numerical Unicode code points (the result of the built-in ' |
| 1680 | 'function\n' |
| 1681 | ' "ord()") of their characters. [3]\n' |
| 1682 | '\n' |
| 1683 | ' Strings and binary sequences cannot be directly compared.\n' |
| 1684 | '\n' |
| 1685 | '* Sequences (instances of "tuple", "list", or "range") can ' |
| 1686 | 'be\n' |
| 1687 | ' compared only within each of their types, with the ' |
| 1688 | 'restriction that\n' |
| 1689 | ' ranges do not support order comparison. Equality ' |
| 1690 | 'comparison across\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1691 | ' these types results in inequality, and ordering comparison ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1692 | 'across\n' |
| 1693 | ' these types raises "TypeError".\n' |
| 1694 | '\n' |
| 1695 | ' Sequences compare lexicographically using comparison of\n' |
| 1696 | ' corresponding elements, whereby reflexivity of the elements ' |
| 1697 | 'is\n' |
| 1698 | ' enforced.\n' |
| 1699 | '\n' |
| 1700 | ' In enforcing reflexivity of elements, the comparison of ' |
| 1701 | 'collections\n' |
| 1702 | ' assumes that for a collection element "x", "x == x" is ' |
| 1703 | 'always true.\n' |
| 1704 | ' Based on that assumption, element identity is compared ' |
| 1705 | 'first, and\n' |
| 1706 | ' element comparison is performed only for distinct ' |
| 1707 | 'elements. This\n' |
| 1708 | ' approach yields the same result as a strict element ' |
| 1709 | 'comparison\n' |
| 1710 | ' would, if the compared elements are reflexive. For ' |
| 1711 | 'non-reflexive\n' |
| 1712 | ' elements, the result is different than for strict element\n' |
| 1713 | ' comparison, and may be surprising: The non-reflexive ' |
| 1714 | 'not-a-number\n' |
| 1715 | ' values for example result in the following comparison ' |
| 1716 | 'behavior when\n' |
| 1717 | ' used in a list:\n' |
| 1718 | '\n' |
| 1719 | " >>> nan = float('NaN')\n" |
| 1720 | ' >>> nan is nan\n' |
| 1721 | ' True\n' |
| 1722 | ' >>> nan == nan\n' |
| 1723 | ' False <-- the defined non-reflexive ' |
| 1724 | 'behavior of NaN\n' |
| 1725 | ' >>> [nan] == [nan]\n' |
| 1726 | ' True <-- list enforces reflexivity and ' |
| 1727 | 'tests identity first\n' |
| 1728 | '\n' |
| 1729 | ' Lexicographical comparison between built-in collections ' |
| 1730 | 'works as\n' |
| 1731 | ' follows:\n' |
| 1732 | '\n' |
| 1733 | ' * For two collections to compare equal, they must be of the ' |
| 1734 | 'same\n' |
| 1735 | ' type, have the same length, and each pair of ' |
| 1736 | 'corresponding\n' |
| 1737 | ' elements must compare equal (for example, "[1,2] == ' |
| 1738 | '(1,2)" is\n' |
| 1739 | ' false because the type is not the same).\n' |
| 1740 | '\n' |
| 1741 | ' * Collections that support order comparison are ordered the ' |
| 1742 | 'same\n' |
| 1743 | ' as their first unequal elements (for example, "[1,2,x] <= ' |
| 1744 | '[1,2,y]"\n' |
| 1745 | ' has the same value as "x <= y"). If a corresponding ' |
| 1746 | 'element does\n' |
| 1747 | ' not exist, the shorter collection is ordered first (for ' |
| 1748 | 'example,\n' |
| 1749 | ' "[1,2] < [1,2,3]" is true).\n' |
| 1750 | '\n' |
| 1751 | '* Mappings (instances of "dict") compare equal if and only if ' |
| 1752 | 'they\n' |
| 1753 | ' have equal *(key, value)* pairs. Equality comparison of the ' |
| 1754 | 'keys and\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1755 | ' values enforces reflexivity.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1756 | '\n' |
| 1757 | ' Order comparisons ("<", ">", "<=", and ">=") raise ' |
| 1758 | '"TypeError".\n' |
| 1759 | '\n' |
| 1760 | '* Sets (instances of "set" or "frozenset") can be compared ' |
| 1761 | 'within\n' |
| 1762 | ' and across their types.\n' |
| 1763 | '\n' |
| 1764 | ' They define order comparison operators to mean subset and ' |
| 1765 | 'superset\n' |
| 1766 | ' tests. Those relations do not define total orderings (for ' |
| 1767 | 'example,\n' |
| 1768 | ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets ' |
| 1769 | 'of one\n' |
| 1770 | ' another, nor supersets of one another). Accordingly, sets ' |
| 1771 | 'are not\n' |
| 1772 | ' appropriate arguments for functions which depend on total ' |
| 1773 | 'ordering\n' |
| 1774 | ' (for example, "min()", "max()", and "sorted()" produce ' |
| 1775 | 'undefined\n' |
| 1776 | ' results given a list of sets as inputs).\n' |
| 1777 | '\n' |
| 1778 | ' Comparison of sets enforces reflexivity of its elements.\n' |
| 1779 | '\n' |
| 1780 | '* Most other built-in types have no comparison methods ' |
| 1781 | 'implemented,\n' |
| 1782 | ' so they inherit the default comparison behavior.\n' |
| 1783 | '\n' |
| 1784 | 'User-defined classes that customize their comparison behavior ' |
| 1785 | 'should\n' |
| 1786 | 'follow some consistency rules, if possible:\n' |
| 1787 | '\n' |
| 1788 | '* Equality comparison should be reflexive. In other words, ' |
| 1789 | 'identical\n' |
| 1790 | ' objects should compare equal:\n' |
| 1791 | '\n' |
| 1792 | ' "x is y" implies "x == y"\n' |
| 1793 | '\n' |
| 1794 | '* Comparison should be symmetric. In other words, the ' |
| 1795 | 'following\n' |
| 1796 | ' expressions should have the same result:\n' |
| 1797 | '\n' |
| 1798 | ' "x == y" and "y == x"\n' |
| 1799 | '\n' |
| 1800 | ' "x != y" and "y != x"\n' |
| 1801 | '\n' |
| 1802 | ' "x < y" and "y > x"\n' |
| 1803 | '\n' |
| 1804 | ' "x <= y" and "y >= x"\n' |
| 1805 | '\n' |
| 1806 | '* Comparison should be transitive. The following ' |
| 1807 | '(non-exhaustive)\n' |
| 1808 | ' examples illustrate that:\n' |
| 1809 | '\n' |
| 1810 | ' "x > y and y > z" implies "x > z"\n' |
| 1811 | '\n' |
| 1812 | ' "x < y and y <= z" implies "x < z"\n' |
| 1813 | '\n' |
| 1814 | '* Inverse comparison should result in the boolean negation. ' |
| 1815 | 'In other\n' |
| 1816 | ' words, the following expressions should have the same ' |
| 1817 | 'result:\n' |
| 1818 | '\n' |
| 1819 | ' "x == y" and "not x != y"\n' |
| 1820 | '\n' |
| 1821 | ' "x < y" and "not x >= y" (for total ordering)\n' |
| 1822 | '\n' |
| 1823 | ' "x > y" and "not x <= y" (for total ordering)\n' |
| 1824 | '\n' |
| 1825 | ' The last two expressions apply to totally ordered ' |
| 1826 | 'collections (e.g.\n' |
| 1827 | ' to sequences, but not to sets or mappings). See also the\n' |
| 1828 | ' "total_ordering()" decorator.\n' |
| 1829 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1830 | '* The "hash()" result should be consistent with equality. ' |
| 1831 | 'Objects\n' |
| 1832 | ' that are equal should either have the same hash value, or ' |
| 1833 | 'be marked\n' |
| 1834 | ' as unhashable.\n' |
| 1835 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1836 | 'Python does not enforce these consistency rules. In fact, ' |
| 1837 | 'the\n' |
| 1838 | 'not-a-number values are an example for not following these ' |
| 1839 | 'rules.\n' |
| 1840 | '\n' |
| 1841 | '\n' |
| 1842 | 'Membership test operations\n' |
| 1843 | '==========================\n' |
| 1844 | '\n' |
| 1845 | 'The operators "in" and "not in" test for membership. "x in ' |
| 1846 | 's"\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1847 | 'evaluates to "True" if *x* is a member of *s*, and "False" ' |
| 1848 | 'otherwise.\n' |
| 1849 | '"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] | 1850 | 'sequences\n' |
| 1851 | 'and set types support this as well as dictionary, for which ' |
| 1852 | '"in" tests\n' |
| 1853 | 'whether the dictionary has a given key. For container types ' |
| 1854 | 'such as\n' |
| 1855 | 'list, tuple, set, frozenset, dict, or collections.deque, the\n' |
| 1856 | 'expression "x in y" is equivalent to "any(x is e or x == e ' |
| 1857 | 'for e in\n' |
| 1858 | 'y)".\n' |
| 1859 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1860 | 'For the string and bytes types, "x in y" is "True" if and ' |
| 1861 | 'only if *x*\n' |
| 1862 | 'is a substring of *y*. An equivalent test is "y.find(x) != ' |
| 1863 | '-1".\n' |
| 1864 | 'Empty strings are always considered to be a substring of any ' |
| 1865 | 'other\n' |
| 1866 | 'string, so """ in "abc"" will return "True".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1867 | '\n' |
| 1868 | 'For user-defined classes which define the "__contains__()" ' |
| 1869 | 'method, "x\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1870 | 'in y" returns "True" if "y.__contains__(x)" returns a true ' |
| 1871 | 'value, and\n' |
| 1872 | '"False" otherwise.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1873 | '\n' |
| 1874 | 'For user-defined classes which do not define "__contains__()" ' |
| 1875 | 'but do\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1876 | 'define "__iter__()", "x in y" is "True" if some value "z" ' |
| 1877 | 'with "x ==\n' |
| 1878 | 'z" is produced while iterating over "y". If an exception is ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1879 | 'raised\n' |
| 1880 | 'during the iteration, it is as if "in" raised that ' |
| 1881 | 'exception.\n' |
| 1882 | '\n' |
| 1883 | 'Lastly, the old-style iteration protocol is tried: if a class ' |
| 1884 | 'defines\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1885 | '"__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] | 1886 | 'non-\n' |
| 1887 | 'negative integer index *i* such that "x == y[i]", and all ' |
| 1888 | 'lower\n' |
| 1889 | 'integer indices do not raise "IndexError" exception. (If any ' |
| 1890 | 'other\n' |
| 1891 | 'exception is raised, it is as if "in" raised that ' |
| 1892 | 'exception).\n' |
| 1893 | '\n' |
| 1894 | 'The operator "not in" is defined to have the inverse true ' |
| 1895 | 'value of\n' |
| 1896 | '"in".\n' |
| 1897 | '\n' |
| 1898 | '\n' |
| 1899 | 'Identity comparisons\n' |
| 1900 | '====================\n' |
| 1901 | '\n' |
| 1902 | 'The operators "is" and "is not" test for object identity: "x ' |
| 1903 | 'is y" is\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 1904 | 'true if and only if *x* and *y* are the same object. Object ' |
| 1905 | 'identity\n' |
| 1906 | 'is determined using the "id()" function. "x is not y" yields ' |
| 1907 | 'the\n' |
| 1908 | 'inverse truth value. [4]\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 1909 | 'compound': 'Compound statements\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 1910 | '*******************\n' |
| 1911 | '\n' |
| 1912 | 'Compound statements contain (groups of) other statements; they ' |
| 1913 | 'affect\n' |
| 1914 | 'or control the execution of those other statements in some way. ' |
| 1915 | 'In\n' |
| 1916 | 'general, compound statements span multiple lines, although in ' |
| 1917 | 'simple\n' |
| 1918 | 'incarnations a whole compound statement may be contained in one ' |
| 1919 | 'line.\n' |
| 1920 | '\n' |
| 1921 | 'The "if", "while" and "for" statements implement traditional ' |
| 1922 | 'control\n' |
| 1923 | 'flow constructs. "try" specifies exception handlers and/or ' |
| 1924 | 'cleanup\n' |
| 1925 | 'code for a group of statements, while the "with" statement ' |
| 1926 | 'allows the\n' |
| 1927 | 'execution of initialization and finalization code around a block ' |
| 1928 | 'of\n' |
| 1929 | 'code. Function and class definitions are also syntactically ' |
| 1930 | 'compound\n' |
| 1931 | 'statements.\n' |
| 1932 | '\n' |
| 1933 | "A compound statement consists of one or more 'clauses.' A " |
| 1934 | 'clause\n' |
| 1935 | "consists of a header and a 'suite.' The clause headers of a\n" |
| 1936 | 'particular compound statement are all at the same indentation ' |
| 1937 | 'level.\n' |
| 1938 | 'Each clause header begins with a uniquely identifying keyword ' |
| 1939 | 'and ends\n' |
| 1940 | 'with a colon. A suite is a group of statements controlled by a\n' |
| 1941 | 'clause. A suite can be one or more semicolon-separated simple\n' |
| 1942 | 'statements on the same line as the header, following the ' |
| 1943 | "header's\n" |
| 1944 | 'colon, or it can be one or more indented statements on ' |
| 1945 | 'subsequent\n' |
| 1946 | 'lines. Only the latter form of a suite can contain nested ' |
| 1947 | 'compound\n' |
| 1948 | "statements; the following is illegal, mostly because it wouldn't " |
| 1949 | 'be\n' |
| 1950 | 'clear to which "if" clause a following "else" clause would ' |
| 1951 | 'belong:\n' |
| 1952 | '\n' |
| 1953 | ' if test1: if test2: print(x)\n' |
| 1954 | '\n' |
| 1955 | 'Also note that the semicolon binds tighter than the colon in ' |
| 1956 | 'this\n' |
| 1957 | 'context, so that in the following example, either all or none of ' |
| 1958 | 'the\n' |
| 1959 | '"print()" calls are executed:\n' |
| 1960 | '\n' |
| 1961 | ' if x < y < z: print(x); print(y); print(z)\n' |
| 1962 | '\n' |
| 1963 | 'Summarizing:\n' |
| 1964 | '\n' |
| 1965 | ' compound_stmt ::= if_stmt\n' |
| 1966 | ' | while_stmt\n' |
| 1967 | ' | for_stmt\n' |
| 1968 | ' | try_stmt\n' |
| 1969 | ' | with_stmt\n' |
| 1970 | ' | funcdef\n' |
| 1971 | ' | classdef\n' |
| 1972 | ' | async_with_stmt\n' |
| 1973 | ' | async_for_stmt\n' |
| 1974 | ' | async_funcdef\n' |
| 1975 | ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' |
| 1976 | 'statement+ DEDENT\n' |
| 1977 | ' statement ::= stmt_list NEWLINE | compound_stmt\n' |
| 1978 | ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n' |
| 1979 | '\n' |
| 1980 | 'Note that statements always end in a "NEWLINE" possibly followed ' |
| 1981 | 'by a\n' |
| 1982 | '"DEDENT". Also note that optional continuation clauses always ' |
| 1983 | 'begin\n' |
| 1984 | 'with a keyword that cannot start a statement, thus there are no\n' |
| 1985 | 'ambiguities (the \'dangling "else"\' problem is solved in Python ' |
| 1986 | 'by\n' |
| 1987 | 'requiring nested "if" statements to be indented).\n' |
| 1988 | '\n' |
| 1989 | 'The formatting of the grammar rules in the following sections ' |
| 1990 | 'places\n' |
| 1991 | 'each clause on a separate line for clarity.\n' |
| 1992 | '\n' |
| 1993 | '\n' |
| 1994 | 'The "if" statement\n' |
| 1995 | '==================\n' |
| 1996 | '\n' |
| 1997 | 'The "if" statement is used for conditional execution:\n' |
| 1998 | '\n' |
| 1999 | ' if_stmt ::= "if" expression ":" suite\n' |
| 2000 | ' ( "elif" expression ":" suite )*\n' |
| 2001 | ' ["else" ":" suite]\n' |
| 2002 | '\n' |
| 2003 | 'It selects exactly one of the suites by evaluating the ' |
| 2004 | 'expressions one\n' |
| 2005 | 'by one until one is found to be true (see section Boolean ' |
| 2006 | 'operations\n' |
| 2007 | 'for the definition of true and false); then that suite is ' |
| 2008 | 'executed\n' |
| 2009 | '(and no other part of the "if" statement is executed or ' |
| 2010 | 'evaluated).\n' |
| 2011 | 'If all expressions are false, the suite of the "else" clause, ' |
| 2012 | 'if\n' |
| 2013 | 'present, is executed.\n' |
| 2014 | '\n' |
| 2015 | '\n' |
| 2016 | 'The "while" statement\n' |
| 2017 | '=====================\n' |
| 2018 | '\n' |
| 2019 | 'The "while" statement is used for repeated execution as long as ' |
| 2020 | 'an\n' |
| 2021 | 'expression is true:\n' |
| 2022 | '\n' |
| 2023 | ' while_stmt ::= "while" expression ":" suite\n' |
| 2024 | ' ["else" ":" suite]\n' |
| 2025 | '\n' |
| 2026 | 'This repeatedly tests the expression and, if it is true, ' |
| 2027 | 'executes the\n' |
| 2028 | 'first suite; if the expression is false (which may be the first ' |
| 2029 | 'time\n' |
| 2030 | 'it is tested) the suite of the "else" clause, if present, is ' |
| 2031 | 'executed\n' |
| 2032 | 'and the loop terminates.\n' |
| 2033 | '\n' |
| 2034 | 'A "break" statement executed in the first suite terminates the ' |
| 2035 | 'loop\n' |
| 2036 | 'without executing the "else" clause\'s suite. A "continue" ' |
| 2037 | 'statement\n' |
| 2038 | 'executed in the first suite skips the rest of the suite and goes ' |
| 2039 | 'back\n' |
| 2040 | 'to testing the expression.\n' |
| 2041 | '\n' |
| 2042 | '\n' |
| 2043 | 'The "for" statement\n' |
| 2044 | '===================\n' |
| 2045 | '\n' |
| 2046 | 'The "for" statement is used to iterate over the elements of a ' |
| 2047 | 'sequence\n' |
| 2048 | '(such as a string, tuple or list) or other iterable object:\n' |
| 2049 | '\n' |
| 2050 | ' for_stmt ::= "for" target_list "in" expression_list ":" ' |
| 2051 | 'suite\n' |
| 2052 | ' ["else" ":" suite]\n' |
| 2053 | '\n' |
| 2054 | 'The expression list is evaluated once; it should yield an ' |
| 2055 | 'iterable\n' |
| 2056 | 'object. An iterator is created for the result of the\n' |
| 2057 | '"expression_list". The suite is then executed once for each ' |
| 2058 | 'item\n' |
| 2059 | 'provided by the iterator, in the order returned by the ' |
| 2060 | 'iterator. Each\n' |
| 2061 | 'item in turn is assigned to the target list using the standard ' |
| 2062 | 'rules\n' |
| 2063 | 'for assignments (see Assignment statements), and then the suite ' |
| 2064 | 'is\n' |
| 2065 | 'executed. When the items are exhausted (which is immediately ' |
| 2066 | 'when the\n' |
| 2067 | 'sequence is empty or an iterator raises a "StopIteration" ' |
| 2068 | 'exception),\n' |
| 2069 | 'the suite in the "else" clause, if present, is executed, and the ' |
| 2070 | 'loop\n' |
| 2071 | 'terminates.\n' |
| 2072 | '\n' |
| 2073 | 'A "break" statement executed in the first suite terminates the ' |
| 2074 | 'loop\n' |
| 2075 | 'without executing the "else" clause\'s suite. A "continue" ' |
| 2076 | 'statement\n' |
| 2077 | 'executed in the first suite skips the rest of the suite and ' |
| 2078 | 'continues\n' |
| 2079 | 'with the next item, or with the "else" clause if there is no ' |
| 2080 | 'next\n' |
| 2081 | 'item.\n' |
| 2082 | '\n' |
| 2083 | 'The for-loop makes assignments to the variables(s) in the target ' |
| 2084 | 'list.\n' |
| 2085 | 'This overwrites all previous assignments to those variables ' |
| 2086 | 'including\n' |
| 2087 | 'those made in the suite of the for-loop:\n' |
| 2088 | '\n' |
| 2089 | ' for i in range(10):\n' |
| 2090 | ' print(i)\n' |
| 2091 | ' i = 5 # this will not affect the for-loop\n' |
| 2092 | ' # because i will be overwritten with ' |
| 2093 | 'the next\n' |
| 2094 | ' # index in the range\n' |
| 2095 | '\n' |
| 2096 | 'Names in the target list are not deleted when the loop is ' |
| 2097 | 'finished,\n' |
| 2098 | 'but if the sequence is empty, they will not have been assigned ' |
| 2099 | 'to at\n' |
| 2100 | 'all by the loop. Hint: the built-in function "range()" returns ' |
| 2101 | 'an\n' |
| 2102 | "iterator of integers suitable to emulate the effect of Pascal's " |
| 2103 | '"for i\n' |
| 2104 | ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' |
| 2105 | '2]".\n' |
| 2106 | '\n' |
| 2107 | 'Note: There is a subtlety when the sequence is being modified by ' |
| 2108 | 'the\n' |
| 2109 | ' loop (this can only occur for mutable sequences, i.e. lists). ' |
| 2110 | 'An\n' |
| 2111 | ' internal counter is used to keep track of which item is used ' |
| 2112 | 'next,\n' |
| 2113 | ' and this is incremented on each iteration. When this counter ' |
| 2114 | 'has\n' |
| 2115 | ' reached the length of the sequence the loop terminates. This ' |
| 2116 | 'means\n' |
| 2117 | ' that if the suite deletes the current (or a previous) item ' |
| 2118 | 'from the\n' |
| 2119 | ' sequence, the next item will be skipped (since it gets the ' |
| 2120 | 'index of\n' |
| 2121 | ' the current item which has already been treated). Likewise, ' |
| 2122 | 'if the\n' |
| 2123 | ' suite inserts an item in the sequence before the current item, ' |
| 2124 | 'the\n' |
| 2125 | ' current item will be treated again the next time through the ' |
| 2126 | 'loop.\n' |
| 2127 | ' This can lead to nasty bugs that can be avoided by making a\n' |
| 2128 | ' temporary copy using a slice of the whole sequence, e.g.,\n' |
| 2129 | '\n' |
| 2130 | ' for x in a[:]:\n' |
| 2131 | ' if x < 0: a.remove(x)\n' |
| 2132 | '\n' |
| 2133 | '\n' |
| 2134 | 'The "try" statement\n' |
| 2135 | '===================\n' |
| 2136 | '\n' |
| 2137 | 'The "try" statement specifies exception handlers and/or cleanup ' |
| 2138 | 'code\n' |
| 2139 | 'for a group of statements:\n' |
| 2140 | '\n' |
| 2141 | ' try_stmt ::= try1_stmt | try2_stmt\n' |
| 2142 | ' try1_stmt ::= "try" ":" suite\n' |
| 2143 | ' ("except" [expression ["as" identifier]] ":" ' |
| 2144 | 'suite)+\n' |
| 2145 | ' ["else" ":" suite]\n' |
| 2146 | ' ["finally" ":" suite]\n' |
| 2147 | ' try2_stmt ::= "try" ":" suite\n' |
| 2148 | ' "finally" ":" suite\n' |
| 2149 | '\n' |
| 2150 | 'The "except" clause(s) specify one or more exception handlers. ' |
| 2151 | 'When no\n' |
| 2152 | 'exception occurs in the "try" clause, no exception handler is\n' |
| 2153 | 'executed. When an exception occurs in the "try" suite, a search ' |
| 2154 | 'for an\n' |
| 2155 | 'exception handler is started. This search inspects the except ' |
| 2156 | 'clauses\n' |
| 2157 | 'in turn until one is found that matches the exception. An ' |
| 2158 | 'expression-\n' |
| 2159 | 'less except clause, if present, must be last; it matches any\n' |
| 2160 | 'exception. For an except clause with an expression, that ' |
| 2161 | 'expression\n' |
| 2162 | 'is evaluated, and the clause matches the exception if the ' |
| 2163 | 'resulting\n' |
| 2164 | 'object is "compatible" with the exception. An object is ' |
| 2165 | 'compatible\n' |
| 2166 | 'with an exception if it is the class or a base class of the ' |
| 2167 | 'exception\n' |
| 2168 | 'object or a tuple containing an item compatible with the ' |
| 2169 | 'exception.\n' |
| 2170 | '\n' |
| 2171 | 'If no except clause matches the exception, the search for an ' |
| 2172 | 'exception\n' |
| 2173 | 'handler continues in the surrounding code and on the invocation ' |
| 2174 | 'stack.\n' |
| 2175 | '[1]\n' |
| 2176 | '\n' |
| 2177 | 'If the evaluation of an expression in the header of an except ' |
| 2178 | 'clause\n' |
| 2179 | 'raises an exception, the original search for a handler is ' |
| 2180 | 'canceled and\n' |
| 2181 | 'a search starts for the new exception in the surrounding code ' |
| 2182 | 'and on\n' |
| 2183 | 'the call stack (it is treated as if the entire "try" statement ' |
| 2184 | 'raised\n' |
| 2185 | 'the exception).\n' |
| 2186 | '\n' |
| 2187 | 'When a matching except clause is found, the exception is ' |
| 2188 | 'assigned to\n' |
| 2189 | 'the target specified after the "as" keyword in that except ' |
| 2190 | 'clause, if\n' |
| 2191 | "present, and the except clause's suite is executed. All except\n" |
| 2192 | 'clauses must have an executable block. When the end of this ' |
| 2193 | 'block is\n' |
| 2194 | 'reached, execution continues normally after the entire try ' |
| 2195 | 'statement.\n' |
| 2196 | '(This means that if two nested handlers exist for the same ' |
| 2197 | 'exception,\n' |
| 2198 | 'and the exception occurs in the try clause of the inner handler, ' |
| 2199 | 'the\n' |
| 2200 | 'outer handler will not handle the exception.)\n' |
| 2201 | '\n' |
| 2202 | 'When an exception has been assigned using "as target", it is ' |
| 2203 | 'cleared\n' |
| 2204 | 'at the end of the except clause. This is as if\n' |
| 2205 | '\n' |
| 2206 | ' except E as N:\n' |
| 2207 | ' foo\n' |
| 2208 | '\n' |
| 2209 | 'was translated to\n' |
| 2210 | '\n' |
| 2211 | ' except E as N:\n' |
| 2212 | ' try:\n' |
| 2213 | ' foo\n' |
| 2214 | ' finally:\n' |
| 2215 | ' del N\n' |
| 2216 | '\n' |
| 2217 | 'This means the exception must be assigned to a different name to ' |
| 2218 | 'be\n' |
| 2219 | 'able to refer to it after the except clause. Exceptions are ' |
| 2220 | 'cleared\n' |
| 2221 | 'because with the traceback attached to them, they form a ' |
| 2222 | 'reference\n' |
| 2223 | 'cycle with the stack frame, keeping all locals in that frame ' |
| 2224 | 'alive\n' |
| 2225 | 'until the next garbage collection occurs.\n' |
| 2226 | '\n' |
| 2227 | "Before an except clause's suite is executed, details about the\n" |
| 2228 | 'exception are stored in the "sys" module and can be accessed ' |
| 2229 | 'via\n' |
| 2230 | '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting ' |
| 2231 | 'of the\n' |
| 2232 | 'exception class, the exception instance and a traceback object ' |
| 2233 | '(see\n' |
| 2234 | 'section The standard type hierarchy) identifying the point in ' |
| 2235 | 'the\n' |
| 2236 | 'program where the exception occurred. "sys.exc_info()" values ' |
| 2237 | 'are\n' |
| 2238 | 'restored to their previous values (before the call) when ' |
| 2239 | 'returning\n' |
| 2240 | 'from a function that handled an exception.\n' |
| 2241 | '\n' |
| 2242 | 'The optional "else" clause is executed if and when control flows ' |
| 2243 | 'off\n' |
| 2244 | 'the end of the "try" clause. [2] Exceptions in the "else" clause ' |
| 2245 | 'are\n' |
| 2246 | 'not handled by the preceding "except" clauses.\n' |
| 2247 | '\n' |
| 2248 | 'If "finally" is present, it specifies a \'cleanup\' handler. ' |
| 2249 | 'The "try"\n' |
| 2250 | 'clause is executed, including any "except" and "else" clauses. ' |
| 2251 | 'If an\n' |
| 2252 | 'exception occurs in any of the clauses and is not handled, the\n' |
| 2253 | 'exception is temporarily saved. The "finally" clause is ' |
| 2254 | 'executed. If\n' |
| 2255 | 'there is a saved exception it is re-raised at the end of the ' |
| 2256 | '"finally"\n' |
| 2257 | 'clause. If the "finally" clause raises another exception, the ' |
| 2258 | 'saved\n' |
| 2259 | 'exception is set as the context of the new exception. If the ' |
| 2260 | '"finally"\n' |
| 2261 | 'clause executes a "return" or "break" statement, the saved ' |
| 2262 | 'exception\n' |
| 2263 | 'is discarded:\n' |
| 2264 | '\n' |
| 2265 | ' >>> def f():\n' |
| 2266 | ' ... try:\n' |
| 2267 | ' ... 1/0\n' |
| 2268 | ' ... finally:\n' |
| 2269 | ' ... return 42\n' |
| 2270 | ' ...\n' |
| 2271 | ' >>> f()\n' |
| 2272 | ' 42\n' |
| 2273 | '\n' |
| 2274 | 'The exception information is not available to the program ' |
| 2275 | 'during\n' |
| 2276 | 'execution of the "finally" clause.\n' |
| 2277 | '\n' |
| 2278 | 'When a "return", "break" or "continue" statement is executed in ' |
| 2279 | 'the\n' |
| 2280 | '"try" suite of a "try"..."finally" statement, the "finally" ' |
| 2281 | 'clause is\n' |
| 2282 | 'also executed \'on the way out.\' A "continue" statement is ' |
| 2283 | 'illegal in\n' |
| 2284 | 'the "finally" clause. (The reason is a problem with the current\n' |
| 2285 | 'implementation --- this restriction may be lifted in the ' |
| 2286 | 'future).\n' |
| 2287 | '\n' |
| 2288 | 'The return value of a function is determined by the last ' |
| 2289 | '"return"\n' |
| 2290 | 'statement executed. Since the "finally" clause always executes, ' |
| 2291 | 'a\n' |
| 2292 | '"return" statement executed in the "finally" clause will always ' |
| 2293 | 'be the\n' |
| 2294 | 'last one executed:\n' |
| 2295 | '\n' |
| 2296 | ' >>> def foo():\n' |
| 2297 | ' ... try:\n' |
| 2298 | " ... return 'try'\n" |
| 2299 | ' ... finally:\n' |
| 2300 | " ... return 'finally'\n" |
| 2301 | ' ...\n' |
| 2302 | ' >>> foo()\n' |
| 2303 | " 'finally'\n" |
| 2304 | '\n' |
| 2305 | 'Additional information on exceptions can be found in section\n' |
| 2306 | 'Exceptions, and information on using the "raise" statement to ' |
| 2307 | 'generate\n' |
| 2308 | 'exceptions may be found in section The raise statement.\n' |
| 2309 | '\n' |
| 2310 | '\n' |
| 2311 | 'The "with" statement\n' |
| 2312 | '====================\n' |
| 2313 | '\n' |
| 2314 | 'The "with" statement is used to wrap the execution of a block ' |
| 2315 | 'with\n' |
| 2316 | 'methods defined by a context manager (see section With ' |
| 2317 | 'Statement\n' |
| 2318 | 'Context Managers). This allows common ' |
| 2319 | '"try"..."except"..."finally"\n' |
| 2320 | 'usage patterns to be encapsulated for convenient reuse.\n' |
| 2321 | '\n' |
| 2322 | ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' |
| 2323 | ' with_item ::= expression ["as" target]\n' |
| 2324 | '\n' |
| 2325 | 'The execution of the "with" statement with one "item" proceeds ' |
| 2326 | 'as\n' |
| 2327 | 'follows:\n' |
| 2328 | '\n' |
| 2329 | '1. The context expression (the expression given in the ' |
| 2330 | '"with_item")\n' |
| 2331 | ' is evaluated to obtain a context manager.\n' |
| 2332 | '\n' |
| 2333 | '2. The context manager\'s "__exit__()" is loaded for later use.\n' |
| 2334 | '\n' |
| 2335 | '3. The context manager\'s "__enter__()" method is invoked.\n' |
| 2336 | '\n' |
| 2337 | '4. If a target was included in the "with" statement, the return\n' |
| 2338 | ' value from "__enter__()" is assigned to it.\n' |
| 2339 | '\n' |
| 2340 | ' Note: The "with" statement guarantees that if the ' |
| 2341 | '"__enter__()"\n' |
| 2342 | ' method returns without an error, then "__exit__()" will ' |
| 2343 | 'always be\n' |
| 2344 | ' called. Thus, if an error occurs during the assignment to ' |
| 2345 | 'the\n' |
| 2346 | ' target list, it will be treated the same as an error ' |
| 2347 | 'occurring\n' |
| 2348 | ' within the suite would be. See step 6 below.\n' |
| 2349 | '\n' |
| 2350 | '5. The suite is executed.\n' |
| 2351 | '\n' |
| 2352 | '6. The context manager\'s "__exit__()" method is invoked. If ' |
| 2353 | 'an\n' |
| 2354 | ' exception caused the suite to be exited, its type, value, ' |
| 2355 | 'and\n' |
| 2356 | ' traceback are passed as arguments to "__exit__()". Otherwise, ' |
| 2357 | 'three\n' |
| 2358 | ' "None" arguments are supplied.\n' |
| 2359 | '\n' |
| 2360 | ' If the suite was exited due to an exception, and the return ' |
| 2361 | 'value\n' |
| 2362 | ' from the "__exit__()" method was false, the exception is ' |
| 2363 | 'reraised.\n' |
| 2364 | ' If the return value was true, the exception is suppressed, ' |
| 2365 | 'and\n' |
| 2366 | ' execution continues with the statement following the "with"\n' |
| 2367 | ' statement.\n' |
| 2368 | '\n' |
| 2369 | ' If the suite was exited for any reason other than an ' |
| 2370 | 'exception, the\n' |
| 2371 | ' return value from "__exit__()" is ignored, and execution ' |
| 2372 | 'proceeds\n' |
| 2373 | ' at the normal location for the kind of exit that was taken.\n' |
| 2374 | '\n' |
| 2375 | 'With more than one item, the context managers are processed as ' |
| 2376 | 'if\n' |
| 2377 | 'multiple "with" statements were nested:\n' |
| 2378 | '\n' |
| 2379 | ' with A() as a, B() as b:\n' |
| 2380 | ' suite\n' |
| 2381 | '\n' |
| 2382 | 'is equivalent to\n' |
| 2383 | '\n' |
| 2384 | ' with A() as a:\n' |
| 2385 | ' with B() as b:\n' |
| 2386 | ' suite\n' |
| 2387 | '\n' |
| 2388 | 'Changed in version 3.1: Support for multiple context ' |
| 2389 | 'expressions.\n' |
| 2390 | '\n' |
| 2391 | 'See also:\n' |
| 2392 | '\n' |
| 2393 | ' **PEP 343** - The "with" statement\n' |
| 2394 | ' The specification, background, and examples for the Python ' |
| 2395 | '"with"\n' |
| 2396 | ' statement.\n' |
| 2397 | '\n' |
| 2398 | '\n' |
| 2399 | 'Function definitions\n' |
| 2400 | '====================\n' |
| 2401 | '\n' |
| 2402 | 'A function definition defines a user-defined function object ' |
| 2403 | '(see\n' |
| 2404 | 'section The standard type hierarchy):\n' |
| 2405 | '\n' |
| 2406 | ' funcdef ::= [decorators] "def" funcname "(" ' |
| 2407 | '[parameter_list] ")" ["->" expression] ":" suite\n' |
| 2408 | ' decorators ::= decorator+\n' |
| 2409 | ' decorator ::= "@" dotted_name ["(" ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 2410 | '[argument_list [","]] ")"] NEWLINE\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2411 | ' dotted_name ::= identifier ("." identifier)*\n' |
| 2412 | ' parameter_list ::= defparameter ("," defparameter)* ' |
| 2413 | '["," [parameter_list_starargs]]\n' |
| 2414 | ' | parameter_list_starargs\n' |
| 2415 | ' parameter_list_starargs ::= "*" [parameter] ("," ' |
| 2416 | 'defparameter)* ["," ["**" parameter [","]]]\n' |
| 2417 | ' | "**" parameter [","]\n' |
| 2418 | ' parameter ::= identifier [":" expression]\n' |
| 2419 | ' defparameter ::= parameter ["=" expression]\n' |
| 2420 | ' funcname ::= identifier\n' |
| 2421 | '\n' |
| 2422 | 'A function definition is an executable statement. Its execution ' |
| 2423 | 'binds\n' |
| 2424 | 'the function name in the current local namespace to a function ' |
| 2425 | 'object\n' |
| 2426 | '(a wrapper around the executable code for the function). This\n' |
| 2427 | 'function object contains a reference to the current global ' |
| 2428 | 'namespace\n' |
| 2429 | 'as the global namespace to be used when the function is called.\n' |
| 2430 | '\n' |
| 2431 | 'The function definition does not execute the function body; this ' |
| 2432 | 'gets\n' |
| 2433 | 'executed only when the function is called. [3]\n' |
| 2434 | '\n' |
| 2435 | 'A function definition may be wrapped by one or more *decorator*\n' |
| 2436 | 'expressions. Decorator expressions are evaluated when the ' |
| 2437 | 'function is\n' |
| 2438 | 'defined, in the scope that contains the function definition. ' |
| 2439 | 'The\n' |
| 2440 | 'result must be a callable, which is invoked with the function ' |
| 2441 | 'object\n' |
| 2442 | 'as the only argument. The returned value is bound to the ' |
| 2443 | 'function name\n' |
| 2444 | 'instead of the function object. Multiple decorators are applied ' |
| 2445 | 'in\n' |
| 2446 | 'nested fashion. For example, the following code\n' |
| 2447 | '\n' |
| 2448 | ' @f1(arg)\n' |
| 2449 | ' @f2\n' |
| 2450 | ' def func(): pass\n' |
| 2451 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2452 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2453 | '\n' |
| 2454 | ' def func(): pass\n' |
| 2455 | ' func = f1(arg)(f2(func))\n' |
| 2456 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2457 | 'except that the original function is not temporarily bound to ' |
| 2458 | 'the name\n' |
| 2459 | '"func".\n' |
| 2460 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2461 | 'When one or more *parameters* have the form *parameter* "="\n' |
| 2462 | '*expression*, the function is said to have "default parameter ' |
| 2463 | 'values."\n' |
| 2464 | 'For a parameter with a default value, the corresponding ' |
| 2465 | '*argument* may\n' |
| 2466 | "be omitted from a call, in which case the parameter's default " |
| 2467 | 'value is\n' |
| 2468 | 'substituted. If a parameter has a default value, all following\n' |
| 2469 | 'parameters up until the ""*"" must also have a default value --- ' |
| 2470 | 'this\n' |
| 2471 | 'is a syntactic restriction that is not expressed by the ' |
| 2472 | 'grammar.\n' |
| 2473 | '\n' |
| 2474 | '**Default parameter values are evaluated from left to right when ' |
| 2475 | 'the\n' |
| 2476 | 'function definition is executed.** This means that the ' |
| 2477 | 'expression is\n' |
| 2478 | 'evaluated once, when the function is defined, and that the same ' |
| 2479 | '"pre-\n' |
| 2480 | 'computed" value is used for each call. This is especially ' |
| 2481 | 'important\n' |
| 2482 | 'to understand when a default parameter is a mutable object, such ' |
| 2483 | 'as a\n' |
| 2484 | 'list or a dictionary: if the function modifies the object (e.g. ' |
| 2485 | 'by\n' |
| 2486 | 'appending an item to a list), the default value is in effect ' |
| 2487 | 'modified.\n' |
| 2488 | 'This is generally not what was intended. A way around this is ' |
| 2489 | 'to use\n' |
| 2490 | '"None" as the default, and explicitly test for it in the body of ' |
| 2491 | 'the\n' |
| 2492 | 'function, e.g.:\n' |
| 2493 | '\n' |
| 2494 | ' def whats_on_the_telly(penguin=None):\n' |
| 2495 | ' if penguin is None:\n' |
| 2496 | ' penguin = []\n' |
| 2497 | ' penguin.append("property of the zoo")\n' |
| 2498 | ' return penguin\n' |
| 2499 | '\n' |
| 2500 | 'Function call semantics are described in more detail in section ' |
| 2501 | 'Calls.\n' |
| 2502 | 'A function call always assigns values to all parameters ' |
| 2503 | 'mentioned in\n' |
| 2504 | 'the parameter list, either from position arguments, from ' |
| 2505 | 'keyword\n' |
| 2506 | 'arguments, or from default values. If the form ""*identifier"" ' |
| 2507 | 'is\n' |
| 2508 | 'present, it is initialized to a tuple receiving any excess ' |
| 2509 | 'positional\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2510 | 'parameters, defaulting to the empty tuple. If the form\n' |
| 2511 | '""**identifier"" is present, it is initialized to a new ordered\n' |
| 2512 | 'mapping receiving any excess keyword arguments, defaulting to a ' |
| 2513 | 'new\n' |
| 2514 | 'empty mapping of the same type. Parameters after ""*"" or\n' |
| 2515 | '""*identifier"" are keyword-only parameters and may only be ' |
| 2516 | 'passed\n' |
| 2517 | 'used keyword arguments.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2518 | '\n' |
| 2519 | 'Parameters may have annotations of the form "": expression"" ' |
| 2520 | 'following\n' |
| 2521 | 'the parameter name. Any parameter may have an annotation even ' |
| 2522 | 'those\n' |
| 2523 | 'of the form "*identifier" or "**identifier". Functions may ' |
| 2524 | 'have\n' |
| 2525 | '"return" annotation of the form ""-> expression"" after the ' |
| 2526 | 'parameter\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 2527 | 'list. These annotations can be any valid Python expression. ' |
| 2528 | 'The\n' |
| 2529 | 'presence of annotations does not change the semantics of a ' |
| 2530 | 'function.\n' |
| 2531 | 'The annotation values are available as values of a dictionary ' |
| 2532 | 'keyed by\n' |
| 2533 | 'the parameters\' names in the "__annotations__" attribute of ' |
| 2534 | 'the\n' |
| 2535 | 'function object. If the "annotations" import from "__future__" ' |
| 2536 | 'is\n' |
| 2537 | 'used, annotations are preserved as strings at runtime which ' |
| 2538 | 'enables\n' |
| 2539 | 'postponed evaluation. Otherwise, they are evaluated when the ' |
| 2540 | 'function\n' |
| 2541 | 'definition is executed. In this case annotations may be ' |
| 2542 | 'evaluated in\n' |
| 2543 | 'a different order than they appear in the source code.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2544 | '\n' |
| 2545 | 'It is also possible to create anonymous functions (functions not ' |
| 2546 | 'bound\n' |
| 2547 | 'to a name), for immediate use in expressions. This uses lambda\n' |
| 2548 | 'expressions, described in section Lambdas. Note that the ' |
| 2549 | 'lambda\n' |
| 2550 | 'expression is merely a shorthand for a simplified function ' |
| 2551 | 'definition;\n' |
| 2552 | 'a function defined in a ""def"" statement can be passed around ' |
| 2553 | 'or\n' |
| 2554 | 'assigned to another name just like a function defined by a ' |
| 2555 | 'lambda\n' |
| 2556 | 'expression. The ""def"" form is actually more powerful since ' |
| 2557 | 'it\n' |
| 2558 | 'allows the execution of multiple statements and annotations.\n' |
| 2559 | '\n' |
| 2560 | "**Programmer's note:** Functions are first-class objects. A " |
| 2561 | '""def""\n' |
| 2562 | 'statement executed inside a function definition defines a local\n' |
| 2563 | 'function that can be returned or passed around. Free variables ' |
| 2564 | 'used\n' |
| 2565 | 'in the nested function can access the local variables of the ' |
| 2566 | 'function\n' |
| 2567 | 'containing the def. See section Naming and binding for ' |
| 2568 | 'details.\n' |
| 2569 | '\n' |
| 2570 | 'See also:\n' |
| 2571 | '\n' |
| 2572 | ' **PEP 3107** - Function Annotations\n' |
| 2573 | ' The original specification for function annotations.\n' |
| 2574 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 2575 | ' **PEP 484** - Type Hints\n' |
| 2576 | ' Definition of a standard meaning for annotations: type ' |
| 2577 | 'hints.\n' |
| 2578 | '\n' |
| 2579 | ' **PEP 526** - Syntax for Variable Annotations\n' |
| 2580 | ' Ability to type hint variable declarations, including ' |
| 2581 | 'class\n' |
| 2582 | ' variables and instance variables\n' |
| 2583 | '\n' |
| 2584 | ' **PEP 563** - Postponed Evaluation of Annotations\n' |
| 2585 | ' Support for forward references within annotations by ' |
| 2586 | 'preserving\n' |
| 2587 | ' annotations in a string form at runtime instead of eager\n' |
| 2588 | ' evaluation.\n' |
| 2589 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2590 | '\n' |
| 2591 | 'Class definitions\n' |
| 2592 | '=================\n' |
| 2593 | '\n' |
| 2594 | 'A class definition defines a class object (see section The ' |
| 2595 | 'standard\n' |
| 2596 | 'type hierarchy):\n' |
| 2597 | '\n' |
| 2598 | ' classdef ::= [decorators] "class" classname [inheritance] ' |
| 2599 | '":" suite\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 2600 | ' inheritance ::= "(" [argument_list] ")"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2601 | ' classname ::= identifier\n' |
| 2602 | '\n' |
| 2603 | 'A class definition is an executable statement. The inheritance ' |
| 2604 | 'list\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2605 | 'usually gives a list of base classes (see Metaclasses for more\n' |
| 2606 | 'advanced uses), so each item in the list should evaluate to a ' |
| 2607 | 'class\n' |
| 2608 | 'object which allows subclassing. Classes without an inheritance ' |
| 2609 | 'list\n' |
| 2610 | 'inherit, by default, from the base class "object"; hence,\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2611 | '\n' |
| 2612 | ' class Foo:\n' |
| 2613 | ' pass\n' |
| 2614 | '\n' |
| 2615 | 'is equivalent to\n' |
| 2616 | '\n' |
| 2617 | ' class Foo(object):\n' |
| 2618 | ' pass\n' |
| 2619 | '\n' |
| 2620 | "The class's suite is then executed in a new execution frame " |
| 2621 | '(see\n' |
| 2622 | 'Naming and binding), using a newly created local namespace and ' |
| 2623 | 'the\n' |
| 2624 | 'original global namespace. (Usually, the suite contains mostly\n' |
| 2625 | "function definitions.) When the class's suite finishes " |
| 2626 | 'execution, its\n' |
| 2627 | 'execution frame is discarded but its local namespace is saved. ' |
| 2628 | '[4] A\n' |
| 2629 | 'class object is then created using the inheritance list for the ' |
| 2630 | 'base\n' |
| 2631 | 'classes and the saved local namespace for the attribute ' |
| 2632 | 'dictionary.\n' |
| 2633 | 'The class name is bound to this class object in the original ' |
| 2634 | 'local\n' |
| 2635 | 'namespace.\n' |
| 2636 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2637 | 'The order in which attributes are defined in the class body is\n' |
| 2638 | 'preserved in the new class\'s "__dict__". Note that this is ' |
| 2639 | 'reliable\n' |
| 2640 | 'only right after the class is created and only for classes that ' |
| 2641 | 'were\n' |
| 2642 | 'defined using the definition syntax.\n' |
| 2643 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2644 | 'Class creation can be customized heavily using metaclasses.\n' |
| 2645 | '\n' |
| 2646 | 'Classes can also be decorated: just like when decorating ' |
| 2647 | 'functions,\n' |
| 2648 | '\n' |
| 2649 | ' @f1(arg)\n' |
| 2650 | ' @f2\n' |
| 2651 | ' class Foo: pass\n' |
| 2652 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2653 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2654 | '\n' |
| 2655 | ' class Foo: pass\n' |
| 2656 | ' Foo = f1(arg)(f2(Foo))\n' |
| 2657 | '\n' |
| 2658 | 'The evaluation rules for the decorator expressions are the same ' |
| 2659 | 'as for\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 2660 | 'function decorators. The result is then bound to the class ' |
| 2661 | 'name.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2662 | '\n' |
| 2663 | "**Programmer's note:** Variables defined in the class definition " |
| 2664 | 'are\n' |
| 2665 | 'class attributes; they are shared by instances. Instance ' |
| 2666 | 'attributes\n' |
| 2667 | 'can be set in a method with "self.name = value". Both class ' |
| 2668 | 'and\n' |
| 2669 | 'instance attributes are accessible through the notation ' |
| 2670 | '""self.name"",\n' |
| 2671 | 'and an instance attribute hides a class attribute with the same ' |
| 2672 | 'name\n' |
| 2673 | 'when accessed in this way. Class attributes can be used as ' |
| 2674 | 'defaults\n' |
| 2675 | 'for instance attributes, but using mutable values there can lead ' |
| 2676 | 'to\n' |
| 2677 | 'unexpected results. Descriptors can be used to create instance\n' |
| 2678 | 'variables with different implementation details.\n' |
| 2679 | '\n' |
| 2680 | 'See also: **PEP 3115** - Metaclasses in Python 3 **PEP 3129** -\n' |
| 2681 | ' Class Decorators\n' |
| 2682 | '\n' |
| 2683 | '\n' |
| 2684 | 'Coroutines\n' |
| 2685 | '==========\n' |
| 2686 | '\n' |
| 2687 | 'New in version 3.5.\n' |
| 2688 | '\n' |
| 2689 | '\n' |
| 2690 | 'Coroutine function definition\n' |
| 2691 | '-----------------------------\n' |
| 2692 | '\n' |
| 2693 | ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' |
| 2694 | '[parameter_list] ")" ["->" expression] ":" suite\n' |
| 2695 | '\n' |
| 2696 | 'Execution of Python coroutines can be suspended and resumed at ' |
| 2697 | 'many\n' |
| 2698 | 'points (see *coroutine*). In the body of a coroutine, any ' |
| 2699 | '"await" and\n' |
| 2700 | '"async" identifiers become reserved keywords; "await" ' |
| 2701 | 'expressions,\n' |
| 2702 | '"async for" and "async with" can only be used in coroutine ' |
| 2703 | 'bodies.\n' |
| 2704 | '\n' |
| 2705 | 'Functions defined with "async def" syntax are always coroutine\n' |
| 2706 | 'functions, even if they do not contain "await" or "async" ' |
| 2707 | 'keywords.\n' |
| 2708 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2709 | 'It is a "SyntaxError" to use "yield from" expressions in "async ' |
| 2710 | 'def"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2711 | 'coroutines.\n' |
| 2712 | '\n' |
| 2713 | 'An example of a coroutine function:\n' |
| 2714 | '\n' |
| 2715 | ' async def func(param1, param2):\n' |
| 2716 | ' do_stuff()\n' |
| 2717 | ' await some_coroutine()\n' |
| 2718 | '\n' |
| 2719 | '\n' |
| 2720 | 'The "async for" statement\n' |
| 2721 | '-------------------------\n' |
| 2722 | '\n' |
| 2723 | ' async_for_stmt ::= "async" for_stmt\n' |
| 2724 | '\n' |
| 2725 | 'An *asynchronous iterable* is able to call asynchronous code in ' |
| 2726 | 'its\n' |
| 2727 | '*iter* implementation, and *asynchronous iterator* can call\n' |
| 2728 | 'asynchronous code in its *next* method.\n' |
| 2729 | '\n' |
| 2730 | 'The "async for" statement allows convenient iteration over\n' |
| 2731 | 'asynchronous iterators.\n' |
| 2732 | '\n' |
| 2733 | 'The following code:\n' |
| 2734 | '\n' |
| 2735 | ' async for TARGET in ITER:\n' |
| 2736 | ' BLOCK\n' |
| 2737 | ' else:\n' |
| 2738 | ' BLOCK2\n' |
| 2739 | '\n' |
| 2740 | 'Is semantically equivalent to:\n' |
| 2741 | '\n' |
| 2742 | ' iter = (ITER)\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 2743 | ' iter = type(iter).__aiter__(iter)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2744 | ' running = True\n' |
| 2745 | ' while running:\n' |
| 2746 | ' try:\n' |
| 2747 | ' TARGET = await type(iter).__anext__(iter)\n' |
| 2748 | ' except StopAsyncIteration:\n' |
| 2749 | ' running = False\n' |
| 2750 | ' else:\n' |
| 2751 | ' BLOCK\n' |
| 2752 | ' else:\n' |
| 2753 | ' BLOCK2\n' |
| 2754 | '\n' |
| 2755 | 'See also "__aiter__()" and "__anext__()" for details.\n' |
| 2756 | '\n' |
| 2757 | 'It is a "SyntaxError" to use "async for" statement outside of ' |
| 2758 | 'an\n' |
| 2759 | '"async def" function.\n' |
| 2760 | '\n' |
| 2761 | '\n' |
| 2762 | 'The "async with" statement\n' |
| 2763 | '--------------------------\n' |
| 2764 | '\n' |
| 2765 | ' async_with_stmt ::= "async" with_stmt\n' |
| 2766 | '\n' |
| 2767 | 'An *asynchronous context manager* is a *context manager* that is ' |
| 2768 | 'able\n' |
| 2769 | 'to suspend execution in its *enter* and *exit* methods.\n' |
| 2770 | '\n' |
| 2771 | 'The following code:\n' |
| 2772 | '\n' |
| 2773 | ' async with EXPR as VAR:\n' |
| 2774 | ' BLOCK\n' |
| 2775 | '\n' |
| 2776 | 'Is semantically equivalent to:\n' |
| 2777 | '\n' |
| 2778 | ' mgr = (EXPR)\n' |
| 2779 | ' aexit = type(mgr).__aexit__\n' |
| 2780 | ' aenter = type(mgr).__aenter__(mgr)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2781 | '\n' |
| 2782 | ' VAR = await aenter\n' |
| 2783 | ' try:\n' |
| 2784 | ' BLOCK\n' |
| 2785 | ' except:\n' |
| 2786 | ' if not await aexit(mgr, *sys.exc_info()):\n' |
| 2787 | ' raise\n' |
| 2788 | ' else:\n' |
| 2789 | ' await aexit(mgr, None, None, None)\n' |
| 2790 | '\n' |
| 2791 | 'See also "__aenter__()" and "__aexit__()" for details.\n' |
| 2792 | '\n' |
| 2793 | 'It is a "SyntaxError" to use "async with" statement outside of ' |
| 2794 | 'an\n' |
| 2795 | '"async def" function.\n' |
| 2796 | '\n' |
| 2797 | 'See also: **PEP 492** - Coroutines with async and await syntax\n' |
| 2798 | '\n' |
| 2799 | '-[ Footnotes ]-\n' |
| 2800 | '\n' |
| 2801 | '[1] The exception is propagated to the invocation stack unless\n' |
| 2802 | ' there is a "finally" clause which happens to raise another\n' |
| 2803 | ' exception. That new exception causes the old one to be ' |
| 2804 | 'lost.\n' |
| 2805 | '\n' |
| 2806 | '[2] Currently, control "flows off the end" except in the case ' |
| 2807 | 'of\n' |
| 2808 | ' an exception or the execution of a "return", "continue", or\n' |
| 2809 | ' "break" statement.\n' |
| 2810 | '\n' |
| 2811 | '[3] A string literal appearing as the first statement in the\n' |
| 2812 | ' function body is transformed into the function\'s "__doc__"\n' |
| 2813 | " attribute and therefore the function's *docstring*.\n" |
| 2814 | '\n' |
| 2815 | '[4] A string literal appearing as the first statement in the ' |
| 2816 | 'class\n' |
| 2817 | ' body is transformed into the namespace\'s "__doc__" item ' |
| 2818 | 'and\n' |
| 2819 | " therefore the class's *docstring*.\n", |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2820 | 'context-managers': 'With Statement Context Managers\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2821 | '*******************************\n' |
| 2822 | '\n' |
| 2823 | 'A *context manager* is an object that defines the ' |
| 2824 | 'runtime context to\n' |
| 2825 | 'be established when executing a "with" statement. The ' |
| 2826 | 'context manager\n' |
| 2827 | 'handles the entry into, and the exit from, the desired ' |
| 2828 | 'runtime context\n' |
| 2829 | 'for the execution of the block of code. Context ' |
| 2830 | 'managers are normally\n' |
| 2831 | 'invoked using the "with" statement (described in section ' |
| 2832 | 'The with\n' |
| 2833 | 'statement), but can also be used by directly invoking ' |
| 2834 | 'their methods.\n' |
| 2835 | '\n' |
| 2836 | 'Typical uses of context managers include saving and ' |
| 2837 | 'restoring various\n' |
| 2838 | 'kinds of global state, locking and unlocking resources, ' |
| 2839 | 'closing opened\n' |
| 2840 | 'files, etc.\n' |
| 2841 | '\n' |
| 2842 | 'For more information on context managers, see Context ' |
| 2843 | 'Manager Types.\n' |
| 2844 | '\n' |
| 2845 | 'object.__enter__(self)\n' |
| 2846 | '\n' |
| 2847 | ' Enter the runtime context related to this object. The ' |
| 2848 | '"with"\n' |
| 2849 | " statement will bind this method's return value to the " |
| 2850 | 'target(s)\n' |
| 2851 | ' specified in the "as" clause of the statement, if ' |
| 2852 | 'any.\n' |
| 2853 | '\n' |
| 2854 | 'object.__exit__(self, exc_type, exc_value, traceback)\n' |
| 2855 | '\n' |
| 2856 | ' Exit the runtime context related to this object. The ' |
| 2857 | 'parameters\n' |
| 2858 | ' describe the exception that caused the context to be ' |
| 2859 | 'exited. If the\n' |
| 2860 | ' context was exited without an exception, all three ' |
| 2861 | 'arguments will\n' |
| 2862 | ' be "None".\n' |
| 2863 | '\n' |
| 2864 | ' If an exception is supplied, and the method wishes to ' |
| 2865 | 'suppress the\n' |
| 2866 | ' exception (i.e., prevent it from being propagated), ' |
| 2867 | 'it should\n' |
| 2868 | ' return a true value. Otherwise, the exception will be ' |
| 2869 | 'processed\n' |
| 2870 | ' normally upon exit from this method.\n' |
| 2871 | '\n' |
| 2872 | ' Note that "__exit__()" methods should not reraise the ' |
| 2873 | 'passed-in\n' |
| 2874 | " exception; this is the caller's responsibility.\n" |
| 2875 | '\n' |
| 2876 | 'See also:\n' |
| 2877 | '\n' |
| 2878 | ' **PEP 343** - The "with" statement\n' |
| 2879 | ' The specification, background, and examples for the ' |
| 2880 | 'Python "with"\n' |
| 2881 | ' statement.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2882 | 'continue': 'The "continue" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2883 | '************************\n' |
| 2884 | '\n' |
| 2885 | ' continue_stmt ::= "continue"\n' |
| 2886 | '\n' |
| 2887 | '"continue" may only occur syntactically nested in a "for" or ' |
| 2888 | '"while"\n' |
| 2889 | 'loop, but not nested in a function or class definition or ' |
| 2890 | '"finally"\n' |
| 2891 | 'clause within that loop. It continues with the next cycle of ' |
| 2892 | 'the\n' |
| 2893 | 'nearest enclosing loop.\n' |
| 2894 | '\n' |
| 2895 | 'When "continue" passes control out of a "try" statement with a\n' |
| 2896 | '"finally" clause, that "finally" clause is executed before ' |
| 2897 | 'really\n' |
| 2898 | 'starting the next loop cycle.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2899 | 'conversions': 'Arithmetic conversions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2900 | '**********************\n' |
| 2901 | '\n' |
| 2902 | 'When a description of an arithmetic operator below uses the ' |
| 2903 | 'phrase\n' |
| 2904 | '"the numeric arguments are converted to a common type," this ' |
| 2905 | 'means\n' |
| 2906 | 'that the operator implementation for built-in types works as ' |
| 2907 | 'follows:\n' |
| 2908 | '\n' |
| 2909 | '* If either argument is a complex number, the other is ' |
| 2910 | 'converted to\n' |
| 2911 | ' complex;\n' |
| 2912 | '\n' |
| 2913 | '* otherwise, if either argument is a floating point number, ' |
| 2914 | 'the\n' |
| 2915 | ' other is converted to floating point;\n' |
| 2916 | '\n' |
| 2917 | '* otherwise, both must be integers and no conversion is ' |
| 2918 | 'necessary.\n' |
| 2919 | '\n' |
| 2920 | 'Some additional rules apply for certain operators (e.g., a ' |
| 2921 | 'string as a\n' |
| 2922 | "left argument to the '%' operator). Extensions must define " |
| 2923 | 'their own\n' |
| 2924 | 'conversion behavior.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2925 | 'customization': 'Basic customization\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2926 | '*******************\n' |
| 2927 | '\n' |
| 2928 | 'object.__new__(cls[, ...])\n' |
| 2929 | '\n' |
| 2930 | ' Called to create a new instance of class *cls*. ' |
| 2931 | '"__new__()" is a\n' |
| 2932 | ' static method (special-cased so you need not declare it ' |
| 2933 | 'as such)\n' |
| 2934 | ' that takes the class of which an instance was requested ' |
| 2935 | 'as its\n' |
| 2936 | ' first argument. The remaining arguments are those ' |
| 2937 | 'passed to the\n' |
| 2938 | ' object constructor expression (the call to the class). ' |
| 2939 | 'The return\n' |
| 2940 | ' value of "__new__()" should be the new object instance ' |
| 2941 | '(usually an\n' |
| 2942 | ' instance of *cls*).\n' |
| 2943 | '\n' |
| 2944 | ' Typical implementations create a new instance of the ' |
| 2945 | 'class by\n' |
| 2946 | ' invoking the superclass\'s "__new__()" method using\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2947 | ' "super().__new__(cls[, ...])" with appropriate arguments ' |
| 2948 | 'and then\n' |
| 2949 | ' modifying the newly-created instance as necessary before ' |
| 2950 | 'returning\n' |
| 2951 | ' it.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2952 | '\n' |
| 2953 | ' If "__new__()" returns an instance of *cls*, then the ' |
| 2954 | 'new\n' |
| 2955 | ' instance\'s "__init__()" method will be invoked like\n' |
| 2956 | ' "__init__(self[, ...])", where *self* is the new ' |
| 2957 | 'instance and the\n' |
| 2958 | ' remaining arguments are the same as were passed to ' |
| 2959 | '"__new__()".\n' |
| 2960 | '\n' |
| 2961 | ' If "__new__()" does not return an instance of *cls*, ' |
| 2962 | 'then the new\n' |
| 2963 | ' instance\'s "__init__()" method will not be invoked.\n' |
| 2964 | '\n' |
| 2965 | ' "__new__()" is intended mainly to allow subclasses of ' |
| 2966 | 'immutable\n' |
| 2967 | ' types (like int, str, or tuple) to customize instance ' |
| 2968 | 'creation. It\n' |
| 2969 | ' is also commonly overridden in custom metaclasses in ' |
| 2970 | 'order to\n' |
| 2971 | ' customize class creation.\n' |
| 2972 | '\n' |
| 2973 | 'object.__init__(self[, ...])\n' |
| 2974 | '\n' |
| 2975 | ' Called after the instance has been created (by ' |
| 2976 | '"__new__()"), but\n' |
| 2977 | ' before it is returned to the caller. The arguments are ' |
| 2978 | 'those\n' |
| 2979 | ' passed to the class constructor expression. If a base ' |
| 2980 | 'class has an\n' |
| 2981 | ' "__init__()" method, the derived class\'s "__init__()" ' |
| 2982 | 'method, if\n' |
| 2983 | ' any, must explicitly call it to ensure proper ' |
| 2984 | 'initialization of the\n' |
| 2985 | ' base class part of the instance; for example:\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 2986 | ' "super().__init__([args...])".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2987 | '\n' |
| 2988 | ' Because "__new__()" and "__init__()" work together in ' |
| 2989 | 'constructing\n' |
| 2990 | ' objects ("__new__()" to create it, and "__init__()" to ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 2991 | 'customize\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 2992 | ' it), no non-"None" value may be returned by ' |
| 2993 | '"__init__()"; doing so\n' |
| 2994 | ' will cause a "TypeError" to be raised at runtime.\n' |
| 2995 | '\n' |
| 2996 | 'object.__del__(self)\n' |
| 2997 | '\n' |
| 2998 | ' Called when the instance is about to be destroyed. This ' |
| 2999 | 'is also\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3000 | ' called a finalizer or (improperly) a destructor. If a ' |
| 3001 | 'base class\n' |
| 3002 | ' has a "__del__()" method, the derived class\'s ' |
| 3003 | '"__del__()" method,\n' |
| 3004 | ' if any, must explicitly call it to ensure proper ' |
| 3005 | 'deletion of the\n' |
| 3006 | ' base class part of the instance.\n' |
| 3007 | '\n' |
| 3008 | ' It is possible (though not recommended!) for the ' |
| 3009 | '"__del__()" method\n' |
| 3010 | ' to postpone destruction of the instance by creating a ' |
| 3011 | 'new reference\n' |
| 3012 | ' to it. This is called object *resurrection*. It is\n' |
| 3013 | ' implementation-dependent whether "__del__()" is called a ' |
| 3014 | 'second\n' |
| 3015 | ' time when a resurrected object is about to be destroyed; ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3016 | 'the\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3017 | ' current *CPython* implementation only calls it once.\n' |
| 3018 | '\n' |
| 3019 | ' It is not guaranteed that "__del__()" methods are called ' |
| 3020 | 'for\n' |
| 3021 | ' objects that still exist when the interpreter exits.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3022 | '\n' |
| 3023 | ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' |
| 3024 | 'the former\n' |
| 3025 | ' decrements the reference count for "x" by one, and the ' |
| 3026 | 'latter is\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3027 | ' only called when "x"\'s reference count reaches zero.\n' |
| 3028 | '\n' |
| 3029 | ' **CPython implementation detail:** It is possible for a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3030 | 'reference\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3031 | ' cycle to prevent the reference count of an object from ' |
| 3032 | 'going to\n' |
| 3033 | ' zero. In this case, the cycle will be later detected ' |
| 3034 | 'and deleted\n' |
| 3035 | ' by the *cyclic garbage collector*. A common cause of ' |
| 3036 | 'reference\n' |
| 3037 | ' cycles is when an exception has been caught in a local ' |
| 3038 | 'variable.\n' |
| 3039 | " The frame's locals then reference the exception, which " |
| 3040 | 'references\n' |
| 3041 | ' its own traceback, which references the locals of all ' |
| 3042 | 'frames caught\n' |
| 3043 | ' in the traceback.\n' |
| 3044 | '\n' |
| 3045 | ' See also: Documentation for the "gc" module.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3046 | '\n' |
| 3047 | ' Warning: Due to the precarious circumstances under ' |
| 3048 | 'which\n' |
| 3049 | ' "__del__()" methods are invoked, exceptions that occur ' |
| 3050 | 'during\n' |
| 3051 | ' their execution are ignored, and a warning is printed ' |
| 3052 | 'to\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3053 | ' "sys.stderr" instead. In particular:\n' |
| 3054 | '\n' |
| 3055 | ' * "__del__()" can be invoked when arbitrary code is ' |
| 3056 | 'being\n' |
| 3057 | ' executed, including from any arbitrary thread. If ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3058 | '"__del__()"\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3059 | ' needs to take a lock or invoke any other blocking ' |
| 3060 | 'resource, it\n' |
| 3061 | ' may deadlock as the resource may already be taken by ' |
| 3062 | 'the code\n' |
| 3063 | ' that gets interrupted to execute "__del__()".\n' |
| 3064 | '\n' |
| 3065 | ' * "__del__()" can be executed during interpreter ' |
| 3066 | 'shutdown. As\n' |
| 3067 | ' a consequence, the global variables it needs to ' |
| 3068 | 'access\n' |
| 3069 | ' (including other modules) may already have been ' |
| 3070 | 'deleted or set\n' |
| 3071 | ' to "None". Python guarantees that globals whose name ' |
| 3072 | 'begins\n' |
| 3073 | ' with a single underscore are deleted from their ' |
| 3074 | 'module before\n' |
| 3075 | ' other globals are deleted; if no other references to ' |
| 3076 | 'such\n' |
| 3077 | ' globals exist, this may help in assuring that ' |
| 3078 | 'imported modules\n' |
| 3079 | ' are still available at the time when the "__del__()" ' |
| 3080 | 'method is\n' |
| 3081 | ' called.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3082 | '\n' |
| 3083 | 'object.__repr__(self)\n' |
| 3084 | '\n' |
| 3085 | ' Called by the "repr()" built-in function to compute the ' |
| 3086 | '"official"\n' |
| 3087 | ' string representation of an object. If at all possible, ' |
| 3088 | 'this\n' |
| 3089 | ' should look like a valid Python expression that could be ' |
| 3090 | 'used to\n' |
| 3091 | ' recreate an object with the same value (given an ' |
| 3092 | 'appropriate\n' |
| 3093 | ' environment). If this is not possible, a string of the ' |
| 3094 | 'form\n' |
| 3095 | ' "<...some useful description...>" should be returned. ' |
| 3096 | 'The return\n' |
| 3097 | ' value must be a string object. If a class defines ' |
| 3098 | '"__repr__()" but\n' |
| 3099 | ' not "__str__()", then "__repr__()" is also used when an ' |
| 3100 | '"informal"\n' |
| 3101 | ' string representation of instances of that class is ' |
| 3102 | 'required.\n' |
| 3103 | '\n' |
| 3104 | ' This is typically used for debugging, so it is important ' |
| 3105 | 'that the\n' |
| 3106 | ' representation is information-rich and unambiguous.\n' |
| 3107 | '\n' |
| 3108 | 'object.__str__(self)\n' |
| 3109 | '\n' |
| 3110 | ' Called by "str(object)" and the built-in functions ' |
| 3111 | '"format()" and\n' |
| 3112 | ' "print()" to compute the "informal" or nicely printable ' |
| 3113 | 'string\n' |
| 3114 | ' representation of an object. The return value must be a ' |
| 3115 | 'string\n' |
| 3116 | ' object.\n' |
| 3117 | '\n' |
| 3118 | ' This method differs from "object.__repr__()" in that ' |
| 3119 | 'there is no\n' |
| 3120 | ' expectation that "__str__()" return a valid Python ' |
| 3121 | 'expression: a\n' |
| 3122 | ' more convenient or concise representation can be used.\n' |
| 3123 | '\n' |
| 3124 | ' The default implementation defined by the built-in type ' |
| 3125 | '"object"\n' |
| 3126 | ' calls "object.__repr__()".\n' |
| 3127 | '\n' |
| 3128 | 'object.__bytes__(self)\n' |
| 3129 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3130 | ' Called by bytes to compute a byte-string representation ' |
| 3131 | 'of an\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3132 | ' object. This should return a "bytes" object.\n' |
| 3133 | '\n' |
| 3134 | 'object.__format__(self, format_spec)\n' |
| 3135 | '\n' |
| 3136 | ' Called by the "format()" built-in function, and by ' |
| 3137 | 'extension,\n' |
| 3138 | ' evaluation of formatted string literals and the ' |
| 3139 | '"str.format()"\n' |
| 3140 | ' method, to produce a "formatted" string representation ' |
| 3141 | 'of an\n' |
| 3142 | ' object. The "format_spec" argument is a string that ' |
| 3143 | 'contains a\n' |
| 3144 | ' description of the formatting options desired. The ' |
| 3145 | 'interpretation\n' |
| 3146 | ' of the "format_spec" argument is up to the type ' |
| 3147 | 'implementing\n' |
| 3148 | ' "__format__()", however most classes will either ' |
| 3149 | 'delegate\n' |
| 3150 | ' formatting to one of the built-in types, or use a ' |
| 3151 | 'similar\n' |
| 3152 | ' formatting option syntax.\n' |
| 3153 | '\n' |
| 3154 | ' See Format Specification Mini-Language for a description ' |
| 3155 | 'of the\n' |
| 3156 | ' standard formatting syntax.\n' |
| 3157 | '\n' |
| 3158 | ' The return value must be a string object.\n' |
| 3159 | '\n' |
| 3160 | ' Changed in version 3.4: The __format__ method of ' |
| 3161 | '"object" itself\n' |
| 3162 | ' raises a "TypeError" if passed any non-empty string.\n' |
| 3163 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3164 | ' Changed in version 3.7: "object.__format__(x, \'\')" is ' |
| 3165 | 'now\n' |
| 3166 | ' equivalent to "str(x)" rather than "format(str(self), ' |
| 3167 | '\'\')".\n' |
| 3168 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3169 | 'object.__lt__(self, other)\n' |
| 3170 | 'object.__le__(self, other)\n' |
| 3171 | 'object.__eq__(self, other)\n' |
| 3172 | 'object.__ne__(self, other)\n' |
| 3173 | 'object.__gt__(self, other)\n' |
| 3174 | 'object.__ge__(self, other)\n' |
| 3175 | '\n' |
| 3176 | ' These are the so-called "rich comparison" methods. The\n' |
| 3177 | ' correspondence between operator symbols and method names ' |
| 3178 | 'is as\n' |
| 3179 | ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' |
| 3180 | '"x.__le__(y)",\n' |
| 3181 | ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' |
| 3182 | '"x>y" calls\n' |
| 3183 | ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' |
| 3184 | '\n' |
| 3185 | ' A rich comparison method may return the singleton ' |
| 3186 | '"NotImplemented"\n' |
| 3187 | ' if it does not implement the operation for a given pair ' |
| 3188 | 'of\n' |
| 3189 | ' arguments. By convention, "False" and "True" are ' |
| 3190 | 'returned for a\n' |
| 3191 | ' successful comparison. However, these methods can return ' |
| 3192 | 'any value,\n' |
| 3193 | ' so if the comparison operator is used in a Boolean ' |
| 3194 | 'context (e.g.,\n' |
| 3195 | ' in the condition of an "if" statement), Python will call ' |
| 3196 | '"bool()"\n' |
| 3197 | ' on the value to determine if the result is true or ' |
| 3198 | 'false.\n' |
| 3199 | '\n' |
| 3200 | ' By default, "__ne__()" delegates to "__eq__()" and ' |
| 3201 | 'inverts the\n' |
| 3202 | ' result unless it is "NotImplemented". There are no ' |
| 3203 | 'other implied\n' |
| 3204 | ' relationships among the comparison operators, for ' |
| 3205 | 'example, the\n' |
| 3206 | ' truth of "(x<y or x==y)" does not imply "x<=y". To ' |
| 3207 | 'automatically\n' |
| 3208 | ' generate ordering operations from a single root ' |
| 3209 | 'operation, see\n' |
| 3210 | ' "functools.total_ordering()".\n' |
| 3211 | '\n' |
| 3212 | ' See the paragraph on "__hash__()" for some important ' |
| 3213 | 'notes on\n' |
| 3214 | ' creating *hashable* objects which support custom ' |
| 3215 | 'comparison\n' |
| 3216 | ' operations and are usable as dictionary keys.\n' |
| 3217 | '\n' |
| 3218 | ' There are no swapped-argument versions of these methods ' |
| 3219 | '(to be used\n' |
| 3220 | ' when the left argument does not support the operation ' |
| 3221 | 'but the right\n' |
| 3222 | ' argument does); rather, "__lt__()" and "__gt__()" are ' |
| 3223 | "each other's\n" |
| 3224 | ' reflection, "__le__()" and "__ge__()" are each other\'s ' |
| 3225 | 'reflection,\n' |
| 3226 | ' and "__eq__()" and "__ne__()" are their own reflection. ' |
| 3227 | 'If the\n' |
| 3228 | " operands are of different types, and right operand's " |
| 3229 | 'type is a\n' |
| 3230 | " direct or indirect subclass of the left operand's type, " |
| 3231 | 'the\n' |
| 3232 | ' reflected method of the right operand has priority, ' |
| 3233 | 'otherwise the\n' |
| 3234 | " left operand's method has priority. Virtual subclassing " |
| 3235 | 'is not\n' |
| 3236 | ' considered.\n' |
| 3237 | '\n' |
| 3238 | 'object.__hash__(self)\n' |
| 3239 | '\n' |
| 3240 | ' Called by built-in function "hash()" and for operations ' |
| 3241 | 'on members\n' |
| 3242 | ' of hashed collections including "set", "frozenset", and ' |
| 3243 | '"dict".\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3244 | ' "__hash__()" should return an integer. The only required ' |
| 3245 | 'property\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3246 | ' is that objects which compare equal have the same hash ' |
| 3247 | 'value; it is\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3248 | ' advised to mix together the hash values of the ' |
| 3249 | 'components of the\n' |
| 3250 | ' object that also play a part in comparison of objects by ' |
| 3251 | 'packing\n' |
| 3252 | ' them into a tuple and hashing the tuple. Example:\n' |
| 3253 | '\n' |
| 3254 | ' def __hash__(self):\n' |
| 3255 | ' return hash((self.name, self.nick, self.color))\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3256 | '\n' |
| 3257 | ' Note: "hash()" truncates the value returned from an ' |
| 3258 | "object's\n" |
| 3259 | ' custom "__hash__()" method to the size of a ' |
| 3260 | '"Py_ssize_t". This\n' |
| 3261 | ' is typically 8 bytes on 64-bit builds and 4 bytes on ' |
| 3262 | '32-bit\n' |
| 3263 | ' builds. If an object\'s "__hash__()" must ' |
| 3264 | 'interoperate on builds\n' |
| 3265 | ' of different bit sizes, be sure to check the width on ' |
| 3266 | 'all\n' |
| 3267 | ' supported builds. An easy way to do this is with ' |
| 3268 | '"python -c\n' |
| 3269 | ' "import sys; print(sys.hash_info.width)"".\n' |
| 3270 | '\n' |
| 3271 | ' If a class does not define an "__eq__()" method it ' |
| 3272 | 'should not\n' |
| 3273 | ' define a "__hash__()" operation either; if it defines ' |
| 3274 | '"__eq__()"\n' |
| 3275 | ' but not "__hash__()", its instances will not be usable ' |
| 3276 | 'as items in\n' |
| 3277 | ' hashable collections. If a class defines mutable ' |
| 3278 | 'objects and\n' |
| 3279 | ' implements an "__eq__()" method, it should not ' |
| 3280 | 'implement\n' |
| 3281 | ' "__hash__()", since the implementation of hashable ' |
| 3282 | 'collections\n' |
| 3283 | " requires that a key's hash value is immutable (if the " |
| 3284 | "object's hash\n" |
| 3285 | ' value changes, it will be in the wrong hash bucket).\n' |
| 3286 | '\n' |
| 3287 | ' User-defined classes have "__eq__()" and "__hash__()" ' |
| 3288 | 'methods by\n' |
| 3289 | ' default; with them, all objects compare unequal (except ' |
| 3290 | 'with\n' |
| 3291 | ' themselves) and "x.__hash__()" returns an appropriate ' |
| 3292 | 'value such\n' |
| 3293 | ' that "x == y" implies both that "x is y" and "hash(x) == ' |
| 3294 | 'hash(y)".\n' |
| 3295 | '\n' |
| 3296 | ' A class that overrides "__eq__()" and does not define ' |
| 3297 | '"__hash__()"\n' |
| 3298 | ' will have its "__hash__()" implicitly set to "None". ' |
| 3299 | 'When the\n' |
| 3300 | ' "__hash__()" method of a class is "None", instances of ' |
| 3301 | 'the class\n' |
| 3302 | ' will raise an appropriate "TypeError" when a program ' |
| 3303 | 'attempts to\n' |
| 3304 | ' retrieve their hash value, and will also be correctly ' |
| 3305 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3306 | ' unhashable when checking "isinstance(obj,\n' |
| 3307 | ' collections.abc.Hashable)".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3308 | '\n' |
| 3309 | ' If a class that overrides "__eq__()" needs to retain ' |
| 3310 | 'the\n' |
| 3311 | ' implementation of "__hash__()" from a parent class, the ' |
| 3312 | 'interpreter\n' |
| 3313 | ' must be told this explicitly by setting "__hash__ =\n' |
| 3314 | ' <ParentClass>.__hash__".\n' |
| 3315 | '\n' |
| 3316 | ' If a class that does not override "__eq__()" wishes to ' |
| 3317 | 'suppress\n' |
| 3318 | ' hash support, it should include "__hash__ = None" in the ' |
| 3319 | 'class\n' |
| 3320 | ' definition. A class which defines its own "__hash__()" ' |
| 3321 | 'that\n' |
| 3322 | ' explicitly raises a "TypeError" would be incorrectly ' |
| 3323 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3324 | ' hashable by an "isinstance(obj, ' |
| 3325 | 'collections.abc.Hashable)" call.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3326 | '\n' |
| 3327 | ' Note: By default, the "__hash__()" values of str, bytes ' |
| 3328 | 'and\n' |
| 3329 | ' datetime objects are "salted" with an unpredictable ' |
| 3330 | 'random value.\n' |
| 3331 | ' Although they remain constant within an individual ' |
| 3332 | 'Python\n' |
| 3333 | ' process, they are not predictable between repeated ' |
| 3334 | 'invocations of\n' |
| 3335 | ' Python.This is intended to provide protection against ' |
| 3336 | 'a denial-\n' |
| 3337 | ' of-service caused by carefully-chosen inputs that ' |
| 3338 | 'exploit the\n' |
| 3339 | ' worst case performance of a dict insertion, O(n^2) ' |
| 3340 | 'complexity.\n' |
| 3341 | ' See ' |
| 3342 | 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' |
| 3343 | ' details.Changing hash values affects the iteration ' |
| 3344 | 'order of\n' |
| 3345 | ' dicts, sets and other mappings. Python has never made ' |
| 3346 | 'guarantees\n' |
| 3347 | ' about this ordering (and it typically varies between ' |
| 3348 | '32-bit and\n' |
| 3349 | ' 64-bit builds).See also "PYTHONHASHSEED".\n' |
| 3350 | '\n' |
| 3351 | ' Changed in version 3.3: Hash randomization is enabled by ' |
| 3352 | 'default.\n' |
| 3353 | '\n' |
| 3354 | 'object.__bool__(self)\n' |
| 3355 | '\n' |
| 3356 | ' Called to implement truth value testing and the built-in ' |
| 3357 | 'operation\n' |
| 3358 | ' "bool()"; should return "False" or "True". When this ' |
| 3359 | 'method is not\n' |
| 3360 | ' defined, "__len__()" is called, if it is defined, and ' |
| 3361 | 'the object is\n' |
| 3362 | ' considered true if its result is nonzero. If a class ' |
| 3363 | 'defines\n' |
| 3364 | ' neither "__len__()" nor "__bool__()", all its instances ' |
| 3365 | 'are\n' |
| 3366 | ' considered true.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3367 | 'debugger': '"pdb" --- The Python Debugger\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3368 | '*****************************\n' |
| 3369 | '\n' |
| 3370 | '**Source code:** Lib/pdb.py\n' |
| 3371 | '\n' |
| 3372 | '======================================================================\n' |
| 3373 | '\n' |
| 3374 | 'The module "pdb" defines an interactive source code debugger ' |
| 3375 | 'for\n' |
| 3376 | 'Python programs. It supports setting (conditional) breakpoints ' |
| 3377 | 'and\n' |
| 3378 | 'single stepping at the source line level, inspection of stack ' |
| 3379 | 'frames,\n' |
| 3380 | 'source code listing, and evaluation of arbitrary Python code in ' |
| 3381 | 'the\n' |
| 3382 | 'context of any stack frame. It also supports post-mortem ' |
| 3383 | 'debugging\n' |
| 3384 | 'and can be called under program control.\n' |
| 3385 | '\n' |
| 3386 | 'The debugger is extensible -- it is actually defined as the ' |
| 3387 | 'class\n' |
| 3388 | '"Pdb". This is currently undocumented but easily understood by ' |
| 3389 | 'reading\n' |
| 3390 | 'the source. The extension interface uses the modules "bdb" and ' |
| 3391 | '"cmd".\n' |
| 3392 | '\n' |
| 3393 | 'The debugger\'s prompt is "(Pdb)". Typical usage to run a ' |
| 3394 | 'program under\n' |
| 3395 | 'control of the debugger is:\n' |
| 3396 | '\n' |
| 3397 | ' >>> import pdb\n' |
| 3398 | ' >>> import mymodule\n' |
| 3399 | " >>> pdb.run('mymodule.test()')\n" |
| 3400 | ' > <string>(0)?()\n' |
| 3401 | ' (Pdb) continue\n' |
| 3402 | ' > <string>(1)?()\n' |
| 3403 | ' (Pdb) continue\n' |
| 3404 | " NameError: 'spam'\n" |
| 3405 | ' > <string>(1)?()\n' |
| 3406 | ' (Pdb)\n' |
| 3407 | '\n' |
| 3408 | 'Changed in version 3.3: Tab-completion via the "readline" module ' |
| 3409 | 'is\n' |
| 3410 | 'available for commands and command arguments, e.g. the current ' |
| 3411 | 'global\n' |
| 3412 | 'and local names are offered as arguments of the "p" command.\n' |
| 3413 | '\n' |
| 3414 | '"pdb.py" can also be invoked as a script to debug other ' |
| 3415 | 'scripts. For\n' |
| 3416 | 'example:\n' |
| 3417 | '\n' |
| 3418 | ' python3 -m pdb myscript.py\n' |
| 3419 | '\n' |
| 3420 | 'When invoked as a script, pdb will automatically enter ' |
| 3421 | 'post-mortem\n' |
| 3422 | 'debugging if the program being debugged exits abnormally. After ' |
| 3423 | 'post-\n' |
| 3424 | 'mortem debugging (or after normal exit of the program), pdb ' |
| 3425 | 'will\n' |
| 3426 | "restart the program. Automatic restarting preserves pdb's state " |
| 3427 | '(such\n' |
| 3428 | 'as breakpoints) and in most cases is more useful than quitting ' |
| 3429 | 'the\n' |
| 3430 | "debugger upon program's exit.\n" |
| 3431 | '\n' |
| 3432 | 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' |
| 3433 | 'executes\n' |
| 3434 | 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n' |
| 3435 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 3436 | 'New in version 3.7: "pdb.py" now accepts a "-m" option that ' |
| 3437 | 'execute\n' |
| 3438 | 'modules similar to the way "python3 -m" does. As with a script, ' |
| 3439 | 'the\n' |
| 3440 | 'debugger will pause execution just before the first line of the\n' |
| 3441 | 'module.\n' |
| 3442 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3443 | 'The typical usage to break into the debugger from a running ' |
| 3444 | 'program is\n' |
| 3445 | 'to insert\n' |
| 3446 | '\n' |
| 3447 | ' import pdb; pdb.set_trace()\n' |
| 3448 | '\n' |
| 3449 | 'at the location you want to break into the debugger. You can ' |
| 3450 | 'then\n' |
| 3451 | 'step through the code following this statement, and continue ' |
| 3452 | 'running\n' |
| 3453 | 'without the debugger using the "continue" command.\n' |
| 3454 | '\n' |
| 3455 | 'The typical usage to inspect a crashed program is:\n' |
| 3456 | '\n' |
| 3457 | ' >>> import pdb\n' |
| 3458 | ' >>> import mymodule\n' |
| 3459 | ' >>> mymodule.test()\n' |
| 3460 | ' Traceback (most recent call last):\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 3461 | ' File "<stdin>", line 1, in <module>\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3462 | ' File "./mymodule.py", line 4, in test\n' |
| 3463 | ' test2()\n' |
| 3464 | ' File "./mymodule.py", line 3, in test2\n' |
| 3465 | ' print(spam)\n' |
| 3466 | ' NameError: spam\n' |
| 3467 | ' >>> pdb.pm()\n' |
| 3468 | ' > ./mymodule.py(3)test2()\n' |
| 3469 | ' -> print(spam)\n' |
| 3470 | ' (Pdb)\n' |
| 3471 | '\n' |
| 3472 | 'The module defines the following functions; each enters the ' |
| 3473 | 'debugger\n' |
| 3474 | 'in a slightly different way:\n' |
| 3475 | '\n' |
| 3476 | 'pdb.run(statement, globals=None, locals=None)\n' |
| 3477 | '\n' |
| 3478 | ' Execute the *statement* (given as a string or a code object) ' |
| 3479 | 'under\n' |
| 3480 | ' debugger control. The debugger prompt appears before any ' |
| 3481 | 'code is\n' |
| 3482 | ' executed; you can set breakpoints and type "continue", or you ' |
| 3483 | 'can\n' |
| 3484 | ' step through the statement using "step" or "next" (all these\n' |
| 3485 | ' commands are explained below). The optional *globals* and ' |
| 3486 | '*locals*\n' |
| 3487 | ' arguments specify the environment in which the code is ' |
| 3488 | 'executed; by\n' |
| 3489 | ' default the dictionary of the module "__main__" is used. ' |
| 3490 | '(See the\n' |
| 3491 | ' explanation of the built-in "exec()" or "eval()" functions.)\n' |
| 3492 | '\n' |
| 3493 | 'pdb.runeval(expression, globals=None, locals=None)\n' |
| 3494 | '\n' |
| 3495 | ' Evaluate the *expression* (given as a string or a code ' |
| 3496 | 'object)\n' |
| 3497 | ' under debugger control. When "runeval()" returns, it returns ' |
| 3498 | 'the\n' |
| 3499 | ' value of the expression. Otherwise this function is similar ' |
| 3500 | 'to\n' |
| 3501 | ' "run()".\n' |
| 3502 | '\n' |
| 3503 | 'pdb.runcall(function, *args, **kwds)\n' |
| 3504 | '\n' |
| 3505 | ' Call the *function* (a function or method object, not a ' |
| 3506 | 'string)\n' |
| 3507 | ' with the given arguments. When "runcall()" returns, it ' |
| 3508 | 'returns\n' |
| 3509 | ' whatever the function call returned. The debugger prompt ' |
| 3510 | 'appears\n' |
| 3511 | ' as soon as the function is entered.\n' |
| 3512 | '\n' |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 3513 | 'pdb.set_trace(*, header=None)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3514 | '\n' |
| 3515 | ' Enter the debugger at the calling stack frame. This is ' |
| 3516 | 'useful to\n' |
| 3517 | ' hard-code a breakpoint at a given point in a program, even if ' |
| 3518 | 'the\n' |
| 3519 | ' code is not otherwise being debugged (e.g. when an assertion\n' |
Ned Deily | 3f9a728 | 2017-12-05 03:17:33 -0500 | [diff] [blame] | 3520 | ' fails). If given, *header* is printed to the console just ' |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 3521 | 'before\n' |
| 3522 | ' debugging begins.\n' |
| 3523 | '\n' |
Ned Deily | 3f9a728 | 2017-12-05 03:17:33 -0500 | [diff] [blame] | 3524 | ' Changed in version 3.7: The keyword-only argument *header*.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3525 | '\n' |
| 3526 | 'pdb.post_mortem(traceback=None)\n' |
| 3527 | '\n' |
| 3528 | ' Enter post-mortem debugging of the given *traceback* object. ' |
| 3529 | 'If no\n' |
| 3530 | ' *traceback* is given, it uses the one of the exception that ' |
| 3531 | 'is\n' |
| 3532 | ' currently being handled (an exception must be being handled ' |
| 3533 | 'if the\n' |
| 3534 | ' default is to be used).\n' |
| 3535 | '\n' |
| 3536 | 'pdb.pm()\n' |
| 3537 | '\n' |
| 3538 | ' Enter post-mortem debugging of the traceback found in\n' |
| 3539 | ' "sys.last_traceback".\n' |
| 3540 | '\n' |
| 3541 | 'The "run*" functions and "set_trace()" are aliases for ' |
| 3542 | 'instantiating\n' |
| 3543 | 'the "Pdb" class and calling the method of the same name. If you ' |
| 3544 | 'want\n' |
| 3545 | 'to access further features, you have to do this yourself:\n' |
| 3546 | '\n' |
| 3547 | "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, " |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 3548 | 'skip=None, nosigint=False, readrc=True)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3549 | '\n' |
| 3550 | ' "Pdb" is the debugger class.\n' |
| 3551 | '\n' |
| 3552 | ' The *completekey*, *stdin* and *stdout* arguments are passed ' |
| 3553 | 'to the\n' |
| 3554 | ' underlying "cmd.Cmd" class; see the description there.\n' |
| 3555 | '\n' |
| 3556 | ' The *skip* argument, if given, must be an iterable of ' |
| 3557 | 'glob-style\n' |
| 3558 | ' module name patterns. The debugger will not step into frames ' |
| 3559 | 'that\n' |
| 3560 | ' originate in a module that matches one of these patterns. ' |
| 3561 | '[1]\n' |
| 3562 | '\n' |
| 3563 | ' By default, Pdb sets a handler for the SIGINT signal (which ' |
| 3564 | 'is sent\n' |
| 3565 | ' when the user presses "Ctrl-C" on the console) when you give ' |
| 3566 | 'a\n' |
| 3567 | ' "continue" command. This allows you to break into the ' |
| 3568 | 'debugger\n' |
| 3569 | ' again by pressing "Ctrl-C". If you want Pdb not to touch ' |
| 3570 | 'the\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 3571 | ' SIGINT handler, set *nosigint* to true.\n' |
| 3572 | '\n' |
| 3573 | ' The *readrc* argument defaults to true and controls whether ' |
| 3574 | 'Pdb\n' |
| 3575 | ' will load .pdbrc files from the filesystem.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3576 | '\n' |
| 3577 | ' Example call to enable tracing with *skip*:\n' |
| 3578 | '\n' |
| 3579 | " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" |
| 3580 | '\n' |
| 3581 | ' New in version 3.1: The *skip* argument.\n' |
| 3582 | '\n' |
| 3583 | ' New in version 3.2: The *nosigint* argument. Previously, a ' |
| 3584 | 'SIGINT\n' |
| 3585 | ' handler was never set by Pdb.\n' |
| 3586 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 3587 | ' Changed in version 3.6: The *readrc* argument.\n' |
| 3588 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3589 | ' run(statement, globals=None, locals=None)\n' |
| 3590 | ' runeval(expression, globals=None, locals=None)\n' |
| 3591 | ' runcall(function, *args, **kwds)\n' |
| 3592 | ' set_trace()\n' |
| 3593 | '\n' |
| 3594 | ' See the documentation for the functions explained above.\n' |
| 3595 | '\n' |
| 3596 | '\n' |
| 3597 | 'Debugger Commands\n' |
| 3598 | '=================\n' |
| 3599 | '\n' |
| 3600 | 'The commands recognized by the debugger are listed below. Most\n' |
| 3601 | 'commands can be abbreviated to one or two letters as indicated; ' |
| 3602 | 'e.g.\n' |
| 3603 | '"h(elp)" means that either "h" or "help" can be used to enter ' |
| 3604 | 'the help\n' |
| 3605 | 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' |
| 3606 | 'Arguments to commands must be separated by whitespace (spaces ' |
| 3607 | 'or\n' |
| 3608 | 'tabs). Optional arguments are enclosed in square brackets ' |
| 3609 | '("[]") in\n' |
| 3610 | 'the command syntax; the square brackets must not be typed.\n' |
| 3611 | 'Alternatives in the command syntax are separated by a vertical ' |
| 3612 | 'bar\n' |
| 3613 | '("|").\n' |
| 3614 | '\n' |
| 3615 | 'Entering a blank line repeats the last command entered. ' |
| 3616 | 'Exception: if\n' |
| 3617 | 'the last command was a "list" command, the next 11 lines are ' |
| 3618 | 'listed.\n' |
| 3619 | '\n' |
| 3620 | "Commands that the debugger doesn't recognize are assumed to be " |
| 3621 | 'Python\n' |
| 3622 | 'statements and are executed in the context of the program being\n' |
| 3623 | 'debugged. Python statements can also be prefixed with an ' |
| 3624 | 'exclamation\n' |
| 3625 | 'point ("!"). This is a powerful way to inspect the program ' |
| 3626 | 'being\n' |
| 3627 | 'debugged; it is even possible to change a variable or call a ' |
| 3628 | 'function.\n' |
| 3629 | 'When an exception occurs in such a statement, the exception name ' |
| 3630 | 'is\n' |
| 3631 | "printed but the debugger's state is not changed.\n" |
| 3632 | '\n' |
| 3633 | 'The debugger supports aliases. Aliases can have parameters ' |
| 3634 | 'which\n' |
| 3635 | 'allows one a certain level of adaptability to the context under\n' |
| 3636 | 'examination.\n' |
| 3637 | '\n' |
| 3638 | 'Multiple commands may be entered on a single line, separated by ' |
| 3639 | '";;".\n' |
| 3640 | '(A single ";" is not used as it is the separator for multiple ' |
| 3641 | 'commands\n' |
| 3642 | 'in a line that is passed to the Python parser.) No intelligence ' |
| 3643 | 'is\n' |
| 3644 | 'applied to separating the commands; the input is split at the ' |
| 3645 | 'first\n' |
| 3646 | '";;" pair, even if it is in the middle of a quoted string.\n' |
| 3647 | '\n' |
| 3648 | 'If a file ".pdbrc" exists in the user\'s home directory or in ' |
| 3649 | 'the\n' |
| 3650 | 'current directory, it is read in and executed as if it had been ' |
| 3651 | 'typed\n' |
| 3652 | 'at the debugger prompt. This is particularly useful for ' |
| 3653 | 'aliases. If\n' |
| 3654 | 'both files exist, the one in the home directory is read first ' |
| 3655 | 'and\n' |
| 3656 | 'aliases defined there can be overridden by the local file.\n' |
| 3657 | '\n' |
| 3658 | 'Changed in version 3.2: ".pdbrc" can now contain commands that\n' |
| 3659 | 'continue debugging, such as "continue" or "next". Previously, ' |
| 3660 | 'these\n' |
| 3661 | 'commands had no effect.\n' |
| 3662 | '\n' |
| 3663 | 'h(elp) [command]\n' |
| 3664 | '\n' |
| 3665 | ' Without argument, print the list of available commands. With ' |
| 3666 | 'a\n' |
| 3667 | ' *command* as argument, print help about that command. "help ' |
| 3668 | 'pdb"\n' |
| 3669 | ' displays the full documentation (the docstring of the "pdb"\n' |
| 3670 | ' module). Since the *command* argument must be an identifier, ' |
| 3671 | '"help\n' |
| 3672 | ' exec" must be entered to get help on the "!" command.\n' |
| 3673 | '\n' |
| 3674 | 'w(here)\n' |
| 3675 | '\n' |
| 3676 | ' Print a stack trace, with the most recent frame at the ' |
| 3677 | 'bottom. An\n' |
| 3678 | ' arrow indicates the current frame, which determines the ' |
| 3679 | 'context of\n' |
| 3680 | ' most commands.\n' |
| 3681 | '\n' |
| 3682 | 'd(own) [count]\n' |
| 3683 | '\n' |
| 3684 | ' Move the current frame *count* (default one) levels down in ' |
| 3685 | 'the\n' |
| 3686 | ' stack trace (to a newer frame).\n' |
| 3687 | '\n' |
| 3688 | 'u(p) [count]\n' |
| 3689 | '\n' |
| 3690 | ' Move the current frame *count* (default one) levels up in the ' |
| 3691 | 'stack\n' |
| 3692 | ' trace (to an older frame).\n' |
| 3693 | '\n' |
| 3694 | 'b(reak) [([filename:]lineno | function) [, condition]]\n' |
| 3695 | '\n' |
| 3696 | ' With a *lineno* argument, set a break there in the current ' |
| 3697 | 'file.\n' |
| 3698 | ' With a *function* argument, set a break at the first ' |
| 3699 | 'executable\n' |
| 3700 | ' statement within that function. The line number may be ' |
| 3701 | 'prefixed\n' |
| 3702 | ' with a filename and a colon, to specify a breakpoint in ' |
| 3703 | 'another\n' |
| 3704 | " file (probably one that hasn't been loaded yet). The file " |
| 3705 | 'is\n' |
| 3706 | ' searched on "sys.path". Note that each breakpoint is ' |
| 3707 | 'assigned a\n' |
| 3708 | ' number to which all the other breakpoint commands refer.\n' |
| 3709 | '\n' |
| 3710 | ' If a second argument is present, it is an expression which ' |
| 3711 | 'must\n' |
| 3712 | ' evaluate to true before the breakpoint is honored.\n' |
| 3713 | '\n' |
| 3714 | ' Without argument, list all breaks, including for each ' |
| 3715 | 'breakpoint,\n' |
| 3716 | ' the number of times that breakpoint has been hit, the ' |
| 3717 | 'current\n' |
| 3718 | ' ignore count, and the associated condition if any.\n' |
| 3719 | '\n' |
| 3720 | 'tbreak [([filename:]lineno | function) [, condition]]\n' |
| 3721 | '\n' |
| 3722 | ' Temporary breakpoint, which is removed automatically when it ' |
| 3723 | 'is\n' |
| 3724 | ' first hit. The arguments are the same as for "break".\n' |
| 3725 | '\n' |
| 3726 | 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n' |
| 3727 | '\n' |
| 3728 | ' With a *filename:lineno* argument, clear all the breakpoints ' |
| 3729 | 'at\n' |
| 3730 | ' this line. With a space separated list of breakpoint numbers, ' |
| 3731 | 'clear\n' |
| 3732 | ' those breakpoints. Without argument, clear all breaks (but ' |
| 3733 | 'first\n' |
| 3734 | ' ask confirmation).\n' |
| 3735 | '\n' |
| 3736 | 'disable [bpnumber [bpnumber ...]]\n' |
| 3737 | '\n' |
| 3738 | ' Disable the breakpoints given as a space separated list of\n' |
| 3739 | ' breakpoint numbers. Disabling a breakpoint means it cannot ' |
| 3740 | 'cause\n' |
| 3741 | ' the program to stop execution, but unlike clearing a ' |
| 3742 | 'breakpoint, it\n' |
| 3743 | ' remains in the list of breakpoints and can be (re-)enabled.\n' |
| 3744 | '\n' |
| 3745 | 'enable [bpnumber [bpnumber ...]]\n' |
| 3746 | '\n' |
| 3747 | ' Enable the breakpoints specified.\n' |
| 3748 | '\n' |
| 3749 | 'ignore bpnumber [count]\n' |
| 3750 | '\n' |
| 3751 | ' Set the ignore count for the given breakpoint number. If ' |
| 3752 | 'count is\n' |
| 3753 | ' omitted, the ignore count is set to 0. A breakpoint becomes ' |
| 3754 | 'active\n' |
| 3755 | ' when the ignore count is zero. When non-zero, the count is\n' |
| 3756 | ' decremented each time the breakpoint is reached and the ' |
| 3757 | 'breakpoint\n' |
| 3758 | ' is not disabled and any associated condition evaluates to ' |
| 3759 | 'true.\n' |
| 3760 | '\n' |
| 3761 | 'condition bpnumber [condition]\n' |
| 3762 | '\n' |
| 3763 | ' Set a new *condition* for the breakpoint, an expression which ' |
| 3764 | 'must\n' |
| 3765 | ' evaluate to true before the breakpoint is honored. If ' |
| 3766 | '*condition*\n' |
| 3767 | ' is absent, any existing condition is removed; i.e., the ' |
| 3768 | 'breakpoint\n' |
| 3769 | ' is made unconditional.\n' |
| 3770 | '\n' |
| 3771 | 'commands [bpnumber]\n' |
| 3772 | '\n' |
| 3773 | ' Specify a list of commands for breakpoint number *bpnumber*. ' |
| 3774 | 'The\n' |
| 3775 | ' commands themselves appear on the following lines. Type a ' |
| 3776 | 'line\n' |
| 3777 | ' containing just "end" to terminate the commands. An example:\n' |
| 3778 | '\n' |
| 3779 | ' (Pdb) commands 1\n' |
| 3780 | ' (com) p some_variable\n' |
| 3781 | ' (com) end\n' |
| 3782 | ' (Pdb)\n' |
| 3783 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3784 | ' To remove all commands from a breakpoint, type "commands" ' |
| 3785 | 'and\n' |
| 3786 | ' follow it immediately with "end"; that is, give no commands.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3787 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3788 | ' With no *bpnumber* argument, "commands" refers to the last\n' |
| 3789 | ' breakpoint set.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3790 | '\n' |
| 3791 | ' You can use breakpoint commands to start your program up ' |
| 3792 | 'again.\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3793 | ' Simply use the "continue" command, or "step", or any other ' |
| 3794 | 'command\n' |
| 3795 | ' that resumes execution.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3796 | '\n' |
| 3797 | ' Specifying any command resuming execution (currently ' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 3798 | '"continue",\n' |
| 3799 | ' "step", "next", "return", "jump", "quit" and their ' |
| 3800 | 'abbreviations)\n' |
| 3801 | ' terminates the command "list" (as if that command was ' |
| 3802 | 'immediately\n' |
| 3803 | ' followed by end). This is because any time you resume ' |
| 3804 | 'execution\n' |
| 3805 | ' (even with a simple next or step), you may encounter another\n' |
| 3806 | ' breakpoint—which could have its own command list, leading to\n' |
| 3807 | ' ambiguities about which list to execute.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3808 | '\n' |
| 3809 | " If you use the 'silent' command in the command list, the " |
| 3810 | 'usual\n' |
| 3811 | ' message about stopping at a breakpoint is not printed. This ' |
| 3812 | 'may be\n' |
| 3813 | ' desirable for breakpoints that are to print a specific ' |
| 3814 | 'message and\n' |
| 3815 | ' then continue. If none of the other commands print anything, ' |
| 3816 | 'you\n' |
| 3817 | ' see no sign that the breakpoint was reached.\n' |
| 3818 | '\n' |
| 3819 | 's(tep)\n' |
| 3820 | '\n' |
| 3821 | ' Execute the current line, stop at the first possible ' |
| 3822 | 'occasion\n' |
| 3823 | ' (either in a function that is called or on the next line in ' |
| 3824 | 'the\n' |
| 3825 | ' current function).\n' |
| 3826 | '\n' |
| 3827 | 'n(ext)\n' |
| 3828 | '\n' |
| 3829 | ' Continue execution until the next line in the current ' |
| 3830 | 'function is\n' |
| 3831 | ' reached or it returns. (The difference between "next" and ' |
| 3832 | '"step"\n' |
| 3833 | ' is that "step" stops inside a called function, while "next"\n' |
| 3834 | ' executes called functions at (nearly) full speed, only ' |
| 3835 | 'stopping at\n' |
| 3836 | ' the next line in the current function.)\n' |
| 3837 | '\n' |
| 3838 | 'unt(il) [lineno]\n' |
| 3839 | '\n' |
| 3840 | ' Without argument, continue execution until the line with a ' |
| 3841 | 'number\n' |
| 3842 | ' greater than the current one is reached.\n' |
| 3843 | '\n' |
| 3844 | ' With a line number, continue execution until a line with a ' |
| 3845 | 'number\n' |
| 3846 | ' greater or equal to that is reached. In both cases, also ' |
| 3847 | 'stop when\n' |
| 3848 | ' the current frame returns.\n' |
| 3849 | '\n' |
| 3850 | ' Changed in version 3.2: Allow giving an explicit line ' |
| 3851 | 'number.\n' |
| 3852 | '\n' |
| 3853 | 'r(eturn)\n' |
| 3854 | '\n' |
| 3855 | ' Continue execution until the current function returns.\n' |
| 3856 | '\n' |
| 3857 | 'c(ont(inue))\n' |
| 3858 | '\n' |
| 3859 | ' Continue execution, only stop when a breakpoint is ' |
| 3860 | 'encountered.\n' |
| 3861 | '\n' |
| 3862 | 'j(ump) lineno\n' |
| 3863 | '\n' |
| 3864 | ' Set the next line that will be executed. Only available in ' |
| 3865 | 'the\n' |
| 3866 | ' bottom-most frame. This lets you jump back and execute code ' |
| 3867 | 'again,\n' |
| 3868 | " or jump forward to skip code that you don't want to run.\n" |
| 3869 | '\n' |
| 3870 | ' It should be noted that not all jumps are allowed -- for ' |
| 3871 | 'instance\n' |
| 3872 | ' it is not possible to jump into the middle of a "for" loop or ' |
| 3873 | 'out\n' |
| 3874 | ' of a "finally" clause.\n' |
| 3875 | '\n' |
| 3876 | 'l(ist) [first[, last]]\n' |
| 3877 | '\n' |
| 3878 | ' List source code for the current file. Without arguments, ' |
| 3879 | 'list 11\n' |
| 3880 | ' lines around the current line or continue the previous ' |
| 3881 | 'listing.\n' |
| 3882 | ' With "." as argument, list 11 lines around the current line. ' |
| 3883 | 'With\n' |
| 3884 | ' one argument, list 11 lines around at that line. With two\n' |
| 3885 | ' arguments, list the given range; if the second argument is ' |
| 3886 | 'less\n' |
| 3887 | ' than the first, it is interpreted as a count.\n' |
| 3888 | '\n' |
| 3889 | ' The current line in the current frame is indicated by "->". ' |
| 3890 | 'If an\n' |
| 3891 | ' exception is being debugged, the line where the exception ' |
| 3892 | 'was\n' |
| 3893 | ' originally raised or propagated is indicated by ">>", if it ' |
| 3894 | 'differs\n' |
| 3895 | ' from the current line.\n' |
| 3896 | '\n' |
| 3897 | ' New in version 3.2: The ">>" marker.\n' |
| 3898 | '\n' |
| 3899 | 'll | longlist\n' |
| 3900 | '\n' |
| 3901 | ' List all source code for the current function or frame.\n' |
| 3902 | ' Interesting lines are marked as for "list".\n' |
| 3903 | '\n' |
| 3904 | ' New in version 3.2.\n' |
| 3905 | '\n' |
| 3906 | 'a(rgs)\n' |
| 3907 | '\n' |
| 3908 | ' Print the argument list of the current function.\n' |
| 3909 | '\n' |
| 3910 | 'p expression\n' |
| 3911 | '\n' |
| 3912 | ' Evaluate the *expression* in the current context and print ' |
| 3913 | 'its\n' |
| 3914 | ' value.\n' |
| 3915 | '\n' |
| 3916 | ' Note: "print()" can also be used, but is not a debugger ' |
| 3917 | 'command\n' |
| 3918 | ' --- this executes the Python "print()" function.\n' |
| 3919 | '\n' |
| 3920 | 'pp expression\n' |
| 3921 | '\n' |
| 3922 | ' Like the "p" command, except the value of the expression is ' |
| 3923 | 'pretty-\n' |
| 3924 | ' printed using the "pprint" module.\n' |
| 3925 | '\n' |
| 3926 | 'whatis expression\n' |
| 3927 | '\n' |
| 3928 | ' Print the type of the *expression*.\n' |
| 3929 | '\n' |
| 3930 | 'source expression\n' |
| 3931 | '\n' |
| 3932 | ' Try to get source code for the given object and display it.\n' |
| 3933 | '\n' |
| 3934 | ' New in version 3.2.\n' |
| 3935 | '\n' |
| 3936 | 'display [expression]\n' |
| 3937 | '\n' |
| 3938 | ' Display the value of the expression if it changed, each time\n' |
| 3939 | ' execution stops in the current frame.\n' |
| 3940 | '\n' |
| 3941 | ' Without expression, list all display expressions for the ' |
| 3942 | 'current\n' |
| 3943 | ' frame.\n' |
| 3944 | '\n' |
| 3945 | ' New in version 3.2.\n' |
| 3946 | '\n' |
| 3947 | 'undisplay [expression]\n' |
| 3948 | '\n' |
| 3949 | ' Do not display the expression any more in the current frame.\n' |
| 3950 | ' Without expression, clear all display expressions for the ' |
| 3951 | 'current\n' |
| 3952 | ' frame.\n' |
| 3953 | '\n' |
| 3954 | ' New in version 3.2.\n' |
| 3955 | '\n' |
| 3956 | 'interact\n' |
| 3957 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 3958 | ' Start an interactive interpreter (using the "code" module) ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 3959 | 'whose\n' |
| 3960 | ' global namespace contains all the (global and local) names ' |
| 3961 | 'found in\n' |
| 3962 | ' the current scope.\n' |
| 3963 | '\n' |
| 3964 | ' New in version 3.2.\n' |
| 3965 | '\n' |
| 3966 | 'alias [name [command]]\n' |
| 3967 | '\n' |
| 3968 | ' Create an alias called *name* that executes *command*. The ' |
| 3969 | 'command\n' |
| 3970 | ' must *not* be enclosed in quotes. Replaceable parameters can ' |
| 3971 | 'be\n' |
| 3972 | ' indicated by "%1", "%2", and so on, while "%*" is replaced by ' |
| 3973 | 'all\n' |
| 3974 | ' the parameters. If no command is given, the current alias ' |
| 3975 | 'for\n' |
| 3976 | ' *name* is shown. If no arguments are given, all aliases are ' |
| 3977 | 'listed.\n' |
| 3978 | '\n' |
| 3979 | ' Aliases may be nested and can contain anything that can be ' |
| 3980 | 'legally\n' |
| 3981 | ' typed at the pdb prompt. Note that internal pdb commands ' |
| 3982 | '*can* be\n' |
| 3983 | ' overridden by aliases. Such a command is then hidden until ' |
| 3984 | 'the\n' |
| 3985 | ' alias is removed. Aliasing is recursively applied to the ' |
| 3986 | 'first\n' |
| 3987 | ' word of the command line; all other words in the line are ' |
| 3988 | 'left\n' |
| 3989 | ' alone.\n' |
| 3990 | '\n' |
| 3991 | ' As an example, here are two useful aliases (especially when ' |
| 3992 | 'placed\n' |
| 3993 | ' in the ".pdbrc" file):\n' |
| 3994 | '\n' |
| 3995 | ' # Print instance variables (usage "pi classInst")\n' |
| 3996 | ' alias pi for k in %1.__dict__.keys(): ' |
| 3997 | 'print("%1.",k,"=",%1.__dict__[k])\n' |
| 3998 | ' # Print instance variables in self\n' |
| 3999 | ' alias ps pi self\n' |
| 4000 | '\n' |
| 4001 | 'unalias name\n' |
| 4002 | '\n' |
| 4003 | ' Delete the specified alias.\n' |
| 4004 | '\n' |
| 4005 | '! statement\n' |
| 4006 | '\n' |
| 4007 | ' Execute the (one-line) *statement* in the context of the ' |
| 4008 | 'current\n' |
| 4009 | ' stack frame. The exclamation point can be omitted unless the ' |
| 4010 | 'first\n' |
| 4011 | ' word of the statement resembles a debugger command. To set ' |
| 4012 | 'a\n' |
| 4013 | ' global variable, you can prefix the assignment command with ' |
| 4014 | 'a\n' |
| 4015 | ' "global" statement on the same line, e.g.:\n' |
| 4016 | '\n' |
| 4017 | " (Pdb) global list_options; list_options = ['-l']\n" |
| 4018 | ' (Pdb)\n' |
| 4019 | '\n' |
| 4020 | 'run [args ...]\n' |
| 4021 | 'restart [args ...]\n' |
| 4022 | '\n' |
| 4023 | ' Restart the debugged Python program. If an argument is ' |
| 4024 | 'supplied,\n' |
| 4025 | ' it is split with "shlex" and the result is used as the new\n' |
| 4026 | ' "sys.argv". History, breakpoints, actions and debugger ' |
| 4027 | 'options are\n' |
| 4028 | ' preserved. "restart" is an alias for "run".\n' |
| 4029 | '\n' |
| 4030 | 'q(uit)\n' |
| 4031 | '\n' |
| 4032 | ' Quit from the debugger. The program being executed is ' |
| 4033 | 'aborted.\n' |
| 4034 | '\n' |
| 4035 | '-[ Footnotes ]-\n' |
| 4036 | '\n' |
| 4037 | '[1] Whether a frame is considered to originate in a certain ' |
| 4038 | 'module\n' |
| 4039 | ' is determined by the "__name__" in the frame globals.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4040 | 'del': 'The "del" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4041 | '*******************\n' |
| 4042 | '\n' |
| 4043 | ' del_stmt ::= "del" target_list\n' |
| 4044 | '\n' |
| 4045 | 'Deletion is recursively defined very similar to the way assignment ' |
| 4046 | 'is\n' |
| 4047 | 'defined. Rather than spelling it out in full details, here are some\n' |
| 4048 | 'hints.\n' |
| 4049 | '\n' |
| 4050 | 'Deletion of a target list recursively deletes each target, from left\n' |
| 4051 | 'to right.\n' |
| 4052 | '\n' |
| 4053 | 'Deletion of a name removes the binding of that name from the local ' |
| 4054 | 'or\n' |
| 4055 | 'global namespace, depending on whether the name occurs in a "global"\n' |
| 4056 | 'statement in the same code block. If the name is unbound, a\n' |
| 4057 | '"NameError" exception will be raised.\n' |
| 4058 | '\n' |
| 4059 | 'Deletion of attribute references, subscriptions and slicings is ' |
| 4060 | 'passed\n' |
| 4061 | 'to the primary object involved; deletion of a slicing is in general\n' |
| 4062 | 'equivalent to assignment of an empty slice of the right type (but ' |
| 4063 | 'even\n' |
| 4064 | 'this is determined by the sliced object).\n' |
| 4065 | '\n' |
| 4066 | 'Changed in version 3.2: Previously it was illegal to delete a name\n' |
| 4067 | 'from the local namespace if it occurs as a free variable in a nested\n' |
| 4068 | 'block.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4069 | 'dict': 'Dictionary displays\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4070 | '*******************\n' |
| 4071 | '\n' |
| 4072 | 'A dictionary display is a possibly empty series of key/datum pairs\n' |
| 4073 | 'enclosed in curly braces:\n' |
| 4074 | '\n' |
| 4075 | ' dict_display ::= "{" [key_datum_list | dict_comprehension] ' |
| 4076 | '"}"\n' |
| 4077 | ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4078 | ' key_datum ::= expression ":" expression | "**" or_expr\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4079 | ' dict_comprehension ::= expression ":" expression comp_for\n' |
| 4080 | '\n' |
| 4081 | 'A dictionary display yields a new dictionary object.\n' |
| 4082 | '\n' |
| 4083 | 'If a comma-separated sequence of key/datum pairs is given, they are\n' |
| 4084 | 'evaluated from left to right to define the entries of the ' |
| 4085 | 'dictionary:\n' |
| 4086 | 'each key object is used as a key into the dictionary to store the\n' |
| 4087 | 'corresponding datum. This means that you can specify the same key\n' |
| 4088 | "multiple times in the key/datum list, and the final dictionary's " |
| 4089 | 'value\n' |
| 4090 | 'for that key will be the last one given.\n' |
| 4091 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4092 | 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n' |
| 4093 | 'must be a *mapping*. Each mapping item is added to the new\n' |
| 4094 | 'dictionary. Later values replace values already set by earlier\n' |
| 4095 | 'key/datum pairs and earlier dictionary unpackings.\n' |
| 4096 | '\n' |
| 4097 | 'New in version 3.5: Unpacking into dictionary displays, originally\n' |
| 4098 | 'proposed by **PEP 448**.\n' |
| 4099 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4100 | 'A dict comprehension, in contrast to list and set comprehensions,\n' |
| 4101 | 'needs two expressions separated with a colon followed by the usual\n' |
| 4102 | '"for" and "if" clauses. When the comprehension is run, the ' |
| 4103 | 'resulting\n' |
| 4104 | 'key and value elements are inserted in the new dictionary in the ' |
| 4105 | 'order\n' |
| 4106 | 'they are produced.\n' |
| 4107 | '\n' |
| 4108 | 'Restrictions on the types of the key values are listed earlier in\n' |
| 4109 | 'section The standard type hierarchy. (To summarize, the key type\n' |
| 4110 | 'should be *hashable*, which excludes all mutable objects.) Clashes\n' |
| 4111 | 'between duplicate keys are not detected; the last datum (textually\n' |
| 4112 | 'rightmost in the display) stored for a given key value prevails.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4113 | 'dynamic-features': 'Interaction with dynamic features\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4114 | '*********************************\n' |
| 4115 | '\n' |
| 4116 | 'Name resolution of free variables occurs at runtime, not ' |
| 4117 | 'at compile\n' |
| 4118 | 'time. This means that the following code will print 42:\n' |
| 4119 | '\n' |
| 4120 | ' i = 10\n' |
| 4121 | ' def f():\n' |
| 4122 | ' print(i)\n' |
| 4123 | ' i = 42\n' |
| 4124 | ' f()\n' |
| 4125 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4126 | 'The "eval()" and "exec()" functions do not have access ' |
| 4127 | 'to the full\n' |
| 4128 | 'environment for resolving names. Names may be resolved ' |
| 4129 | 'in the local\n' |
| 4130 | 'and global namespaces of the caller. Free variables are ' |
| 4131 | 'not resolved\n' |
| 4132 | 'in the nearest enclosing namespace, but in the global ' |
| 4133 | 'namespace. [1]\n' |
| 4134 | 'The "exec()" and "eval()" functions have optional ' |
| 4135 | 'arguments to\n' |
| 4136 | 'override the global and local namespace. If only one ' |
| 4137 | 'namespace is\n' |
| 4138 | 'specified, it is used for both.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4139 | 'else': 'The "if" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4140 | '******************\n' |
| 4141 | '\n' |
| 4142 | 'The "if" statement is used for conditional execution:\n' |
| 4143 | '\n' |
| 4144 | ' if_stmt ::= "if" expression ":" suite\n' |
| 4145 | ' ( "elif" expression ":" suite )*\n' |
| 4146 | ' ["else" ":" suite]\n' |
| 4147 | '\n' |
| 4148 | 'It selects exactly one of the suites by evaluating the expressions ' |
| 4149 | 'one\n' |
| 4150 | 'by one until one is found to be true (see section Boolean ' |
| 4151 | 'operations\n' |
| 4152 | 'for the definition of true and false); then that suite is executed\n' |
| 4153 | '(and no other part of the "if" statement is executed or evaluated).\n' |
| 4154 | 'If all expressions are false, the suite of the "else" clause, if\n' |
| 4155 | 'present, is executed.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4156 | 'exceptions': 'Exceptions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4157 | '**********\n' |
| 4158 | '\n' |
| 4159 | 'Exceptions are a means of breaking out of the normal flow of ' |
| 4160 | 'control\n' |
| 4161 | 'of a code block in order to handle errors or other ' |
| 4162 | 'exceptional\n' |
| 4163 | 'conditions. An exception is *raised* at the point where the ' |
| 4164 | 'error is\n' |
| 4165 | 'detected; it may be *handled* by the surrounding code block or ' |
| 4166 | 'by any\n' |
| 4167 | 'code block that directly or indirectly invoked the code block ' |
| 4168 | 'where\n' |
| 4169 | 'the error occurred.\n' |
| 4170 | '\n' |
| 4171 | 'The Python interpreter raises an exception when it detects a ' |
| 4172 | 'run-time\n' |
| 4173 | 'error (such as division by zero). A Python program can also\n' |
| 4174 | 'explicitly raise an exception with the "raise" statement. ' |
| 4175 | 'Exception\n' |
| 4176 | 'handlers are specified with the "try" ... "except" statement. ' |
| 4177 | 'The\n' |
| 4178 | '"finally" clause of such a statement can be used to specify ' |
| 4179 | 'cleanup\n' |
| 4180 | 'code which does not handle the exception, but is executed ' |
| 4181 | 'whether an\n' |
| 4182 | 'exception occurred or not in the preceding code.\n' |
| 4183 | '\n' |
| 4184 | 'Python uses the "termination" model of error handling: an ' |
| 4185 | 'exception\n' |
| 4186 | 'handler can find out what happened and continue execution at ' |
| 4187 | 'an outer\n' |
| 4188 | 'level, but it cannot repair the cause of the error and retry ' |
| 4189 | 'the\n' |
| 4190 | 'failing operation (except by re-entering the offending piece ' |
| 4191 | 'of code\n' |
| 4192 | 'from the top).\n' |
| 4193 | '\n' |
| 4194 | 'When an exception is not handled at all, the interpreter ' |
| 4195 | 'terminates\n' |
| 4196 | 'execution of the program, or returns to its interactive main ' |
| 4197 | 'loop. In\n' |
| 4198 | 'either case, it prints a stack backtrace, except when the ' |
| 4199 | 'exception is\n' |
| 4200 | '"SystemExit".\n' |
| 4201 | '\n' |
| 4202 | 'Exceptions are identified by class instances. The "except" ' |
| 4203 | 'clause is\n' |
| 4204 | 'selected depending on the class of the instance: it must ' |
| 4205 | 'reference the\n' |
| 4206 | 'class of the instance or a base class thereof. The instance ' |
| 4207 | 'can be\n' |
| 4208 | 'received by the handler and can carry additional information ' |
| 4209 | 'about the\n' |
| 4210 | 'exceptional condition.\n' |
| 4211 | '\n' |
| 4212 | 'Note: Exception messages are not part of the Python API. ' |
| 4213 | 'Their\n' |
| 4214 | ' contents may change from one version of Python to the next ' |
| 4215 | 'without\n' |
| 4216 | ' warning and should not be relied on by code which will run ' |
| 4217 | 'under\n' |
| 4218 | ' multiple versions of the interpreter.\n' |
| 4219 | '\n' |
| 4220 | 'See also the description of the "try" statement in section The ' |
| 4221 | 'try\n' |
| 4222 | 'statement and "raise" statement in section The raise ' |
| 4223 | 'statement.\n' |
| 4224 | '\n' |
| 4225 | '-[ Footnotes ]-\n' |
| 4226 | '\n' |
| 4227 | '[1] This limitation occurs because the code that is executed ' |
| 4228 | 'by\n' |
| 4229 | ' these operations is not available at the time the module ' |
| 4230 | 'is\n' |
| 4231 | ' compiled.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4232 | 'execmodel': 'Execution model\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4233 | '***************\n' |
| 4234 | '\n' |
| 4235 | '\n' |
| 4236 | 'Structure of a program\n' |
| 4237 | '======================\n' |
| 4238 | '\n' |
| 4239 | 'A Python program is constructed from code blocks. A *block* is ' |
| 4240 | 'a piece\n' |
| 4241 | 'of Python program text that is executed as a unit. The ' |
| 4242 | 'following are\n' |
| 4243 | 'blocks: a module, a function body, and a class definition. ' |
| 4244 | 'Each\n' |
| 4245 | 'command typed interactively is a block. A script file (a file ' |
| 4246 | 'given\n' |
| 4247 | 'as standard input to the interpreter or specified as a command ' |
| 4248 | 'line\n' |
| 4249 | 'argument to the interpreter) is a code block. A script command ' |
| 4250 | '(a\n' |
| 4251 | 'command specified on the interpreter command line with the ' |
| 4252 | "'**-c**'\n" |
| 4253 | 'option) is a code block. The string argument passed to the ' |
| 4254 | 'built-in\n' |
| 4255 | 'functions "eval()" and "exec()" is a code block.\n' |
| 4256 | '\n' |
| 4257 | 'A code block is executed in an *execution frame*. A frame ' |
| 4258 | 'contains\n' |
| 4259 | 'some administrative information (used for debugging) and ' |
| 4260 | 'determines\n' |
| 4261 | "where and how execution continues after the code block's " |
| 4262 | 'execution has\n' |
| 4263 | 'completed.\n' |
| 4264 | '\n' |
| 4265 | '\n' |
| 4266 | 'Naming and binding\n' |
| 4267 | '==================\n' |
| 4268 | '\n' |
| 4269 | '\n' |
| 4270 | 'Binding of names\n' |
| 4271 | '----------------\n' |
| 4272 | '\n' |
| 4273 | '*Names* refer to objects. Names are introduced by name ' |
| 4274 | 'binding\n' |
| 4275 | 'operations.\n' |
| 4276 | '\n' |
| 4277 | 'The following constructs bind names: formal parameters to ' |
| 4278 | 'functions,\n' |
| 4279 | '"import" statements, class and function definitions (these bind ' |
| 4280 | 'the\n' |
| 4281 | 'class or function name in the defining block), and targets that ' |
| 4282 | 'are\n' |
| 4283 | 'identifiers if occurring in an assignment, "for" loop header, ' |
| 4284 | 'or after\n' |
| 4285 | '"as" in a "with" statement or "except" clause. The "import" ' |
| 4286 | 'statement\n' |
| 4287 | 'of the form "from ... import *" binds all names defined in the\n' |
| 4288 | 'imported module, except those beginning with an underscore. ' |
| 4289 | 'This form\n' |
| 4290 | 'may only be used at the module level.\n' |
| 4291 | '\n' |
| 4292 | 'A target occurring in a "del" statement is also considered ' |
| 4293 | 'bound for\n' |
| 4294 | 'this purpose (though the actual semantics are to unbind the ' |
| 4295 | 'name).\n' |
| 4296 | '\n' |
| 4297 | 'Each assignment or import statement occurs within a block ' |
| 4298 | 'defined by a\n' |
| 4299 | 'class or function definition or at the module level (the ' |
| 4300 | 'top-level\n' |
| 4301 | 'code block).\n' |
| 4302 | '\n' |
| 4303 | 'If a name is bound in a block, it is a local variable of that ' |
| 4304 | 'block,\n' |
| 4305 | 'unless declared as "nonlocal" or "global". If a name is bound ' |
| 4306 | 'at the\n' |
| 4307 | 'module level, it is a global variable. (The variables of the ' |
| 4308 | 'module\n' |
| 4309 | 'code block are local and global.) If a variable is used in a ' |
| 4310 | 'code\n' |
| 4311 | 'block but not defined there, it is a *free variable*.\n' |
| 4312 | '\n' |
| 4313 | 'Each occurrence of a name in the program text refers to the ' |
| 4314 | '*binding*\n' |
| 4315 | 'of that name established by the following name resolution ' |
| 4316 | 'rules.\n' |
| 4317 | '\n' |
| 4318 | '\n' |
| 4319 | 'Resolution of names\n' |
| 4320 | '-------------------\n' |
| 4321 | '\n' |
| 4322 | 'A *scope* defines the visibility of a name within a block. If ' |
| 4323 | 'a local\n' |
| 4324 | 'variable is defined in a block, its scope includes that block. ' |
| 4325 | 'If the\n' |
| 4326 | 'definition occurs in a function block, the scope extends to any ' |
| 4327 | 'blocks\n' |
| 4328 | 'contained within the defining one, unless a contained block ' |
| 4329 | 'introduces\n' |
| 4330 | 'a different binding for the name.\n' |
| 4331 | '\n' |
| 4332 | 'When a name is used in a code block, it is resolved using the ' |
| 4333 | 'nearest\n' |
| 4334 | 'enclosing scope. The set of all such scopes visible to a code ' |
| 4335 | 'block\n' |
| 4336 | "is called the block's *environment*.\n" |
| 4337 | '\n' |
| 4338 | 'When a name is not found at all, a "NameError" exception is ' |
| 4339 | 'raised. If\n' |
| 4340 | 'the current scope is a function scope, and the name refers to a ' |
| 4341 | 'local\n' |
| 4342 | 'variable that has not yet been bound to a value at the point ' |
| 4343 | 'where the\n' |
| 4344 | 'name is used, an "UnboundLocalError" exception is raised.\n' |
| 4345 | '"UnboundLocalError" is a subclass of "NameError".\n' |
| 4346 | '\n' |
| 4347 | 'If a name binding operation occurs anywhere within a code ' |
| 4348 | 'block, all\n' |
| 4349 | 'uses of the name within the block are treated as references to ' |
| 4350 | 'the\n' |
| 4351 | 'current block. This can lead to errors when a name is used ' |
| 4352 | 'within a\n' |
| 4353 | 'block before it is bound. This rule is subtle. Python lacks\n' |
| 4354 | 'declarations and allows name binding operations to occur ' |
| 4355 | 'anywhere\n' |
| 4356 | 'within a code block. The local variables of a code block can ' |
| 4357 | 'be\n' |
| 4358 | 'determined by scanning the entire text of the block for name ' |
| 4359 | 'binding\n' |
| 4360 | 'operations.\n' |
| 4361 | '\n' |
| 4362 | 'If the "global" statement occurs within a block, all uses of ' |
| 4363 | 'the name\n' |
| 4364 | 'specified in the statement refer to the binding of that name in ' |
| 4365 | 'the\n' |
| 4366 | 'top-level namespace. Names are resolved in the top-level ' |
| 4367 | 'namespace by\n' |
| 4368 | 'searching the global namespace, i.e. the namespace of the ' |
| 4369 | 'module\n' |
| 4370 | 'containing the code block, and the builtins namespace, the ' |
| 4371 | 'namespace\n' |
| 4372 | 'of the module "builtins". The global namespace is searched ' |
| 4373 | 'first. If\n' |
| 4374 | 'the name is not found there, the builtins namespace is ' |
| 4375 | 'searched. The\n' |
| 4376 | '"global" statement must precede all uses of the name.\n' |
| 4377 | '\n' |
| 4378 | 'The "global" statement has the same scope as a name binding ' |
| 4379 | 'operation\n' |
| 4380 | 'in the same block. If the nearest enclosing scope for a free ' |
| 4381 | 'variable\n' |
| 4382 | 'contains a global statement, the free variable is treated as a ' |
| 4383 | 'global.\n' |
| 4384 | '\n' |
| 4385 | 'The "nonlocal" statement causes corresponding names to refer ' |
| 4386 | 'to\n' |
| 4387 | 'previously bound variables in the nearest enclosing function ' |
| 4388 | 'scope.\n' |
| 4389 | '"SyntaxError" is raised at compile time if the given name does ' |
| 4390 | 'not\n' |
| 4391 | 'exist in any enclosing function scope.\n' |
| 4392 | '\n' |
| 4393 | 'The namespace for a module is automatically created the first ' |
| 4394 | 'time a\n' |
| 4395 | 'module is imported. The main module for a script is always ' |
| 4396 | 'called\n' |
| 4397 | '"__main__".\n' |
| 4398 | '\n' |
| 4399 | 'Class definition blocks and arguments to "exec()" and "eval()" ' |
| 4400 | 'are\n' |
| 4401 | 'special in the context of name resolution. A class definition ' |
| 4402 | 'is an\n' |
| 4403 | 'executable statement that may use and define names. These ' |
| 4404 | 'references\n' |
| 4405 | 'follow the normal rules for name resolution with an exception ' |
| 4406 | 'that\n' |
| 4407 | 'unbound local variables are looked up in the global namespace. ' |
| 4408 | 'The\n' |
| 4409 | 'namespace of the class definition becomes the attribute ' |
| 4410 | 'dictionary of\n' |
| 4411 | 'the class. The scope of names defined in a class block is ' |
| 4412 | 'limited to\n' |
| 4413 | 'the class block; it does not extend to the code blocks of ' |
| 4414 | 'methods --\n' |
| 4415 | 'this includes comprehensions and generator expressions since ' |
| 4416 | 'they are\n' |
| 4417 | 'implemented using a function scope. This means that the ' |
| 4418 | 'following\n' |
| 4419 | 'will fail:\n' |
| 4420 | '\n' |
| 4421 | ' class A:\n' |
| 4422 | ' a = 42\n' |
| 4423 | ' b = list(a + i for i in range(10))\n' |
| 4424 | '\n' |
| 4425 | '\n' |
| 4426 | 'Builtins and restricted execution\n' |
| 4427 | '---------------------------------\n' |
| 4428 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4429 | '**CPython implementation detail:** Users should not touch\n' |
| 4430 | '"__builtins__"; it is strictly an implementation detail. ' |
| 4431 | 'Users\n' |
| 4432 | 'wanting to override values in the builtins namespace should ' |
| 4433 | '"import"\n' |
| 4434 | 'the "builtins" module and modify its attributes appropriately.\n' |
| 4435 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4436 | 'The builtins namespace associated with the execution of a code ' |
| 4437 | 'block\n' |
| 4438 | 'is actually found by looking up the name "__builtins__" in its ' |
| 4439 | 'global\n' |
| 4440 | 'namespace; this should be a dictionary or a module (in the ' |
| 4441 | 'latter case\n' |
| 4442 | "the module's dictionary is used). By default, when in the " |
| 4443 | '"__main__"\n' |
| 4444 | 'module, "__builtins__" is the built-in module "builtins"; when ' |
| 4445 | 'in any\n' |
| 4446 | 'other module, "__builtins__" is an alias for the dictionary of ' |
| 4447 | 'the\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4448 | '"builtins" module itself.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4449 | '\n' |
| 4450 | '\n' |
| 4451 | 'Interaction with dynamic features\n' |
| 4452 | '---------------------------------\n' |
| 4453 | '\n' |
| 4454 | 'Name resolution of free variables occurs at runtime, not at ' |
| 4455 | 'compile\n' |
| 4456 | 'time. This means that the following code will print 42:\n' |
| 4457 | '\n' |
| 4458 | ' i = 10\n' |
| 4459 | ' def f():\n' |
| 4460 | ' print(i)\n' |
| 4461 | ' i = 42\n' |
| 4462 | ' f()\n' |
| 4463 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4464 | 'The "eval()" and "exec()" functions do not have access to the ' |
| 4465 | 'full\n' |
| 4466 | 'environment for resolving names. Names may be resolved in the ' |
| 4467 | 'local\n' |
| 4468 | 'and global namespaces of the caller. Free variables are not ' |
| 4469 | 'resolved\n' |
| 4470 | 'in the nearest enclosing namespace, but in the global ' |
| 4471 | 'namespace. [1]\n' |
| 4472 | 'The "exec()" and "eval()" functions have optional arguments to\n' |
| 4473 | 'override the global and local namespace. If only one namespace ' |
| 4474 | 'is\n' |
| 4475 | 'specified, it is used for both.\n' |
| 4476 | '\n' |
| 4477 | '\n' |
| 4478 | 'Exceptions\n' |
| 4479 | '==========\n' |
| 4480 | '\n' |
| 4481 | 'Exceptions are a means of breaking out of the normal flow of ' |
| 4482 | 'control\n' |
| 4483 | 'of a code block in order to handle errors or other exceptional\n' |
| 4484 | 'conditions. An exception is *raised* at the point where the ' |
| 4485 | 'error is\n' |
| 4486 | 'detected; it may be *handled* by the surrounding code block or ' |
| 4487 | 'by any\n' |
| 4488 | 'code block that directly or indirectly invoked the code block ' |
| 4489 | 'where\n' |
| 4490 | 'the error occurred.\n' |
| 4491 | '\n' |
| 4492 | 'The Python interpreter raises an exception when it detects a ' |
| 4493 | 'run-time\n' |
| 4494 | 'error (such as division by zero). A Python program can also\n' |
| 4495 | 'explicitly raise an exception with the "raise" statement. ' |
| 4496 | 'Exception\n' |
| 4497 | 'handlers are specified with the "try" ... "except" statement. ' |
| 4498 | 'The\n' |
| 4499 | '"finally" clause of such a statement can be used to specify ' |
| 4500 | 'cleanup\n' |
| 4501 | 'code which does not handle the exception, but is executed ' |
| 4502 | 'whether an\n' |
| 4503 | 'exception occurred or not in the preceding code.\n' |
| 4504 | '\n' |
| 4505 | 'Python uses the "termination" model of error handling: an ' |
| 4506 | 'exception\n' |
| 4507 | 'handler can find out what happened and continue execution at an ' |
| 4508 | 'outer\n' |
| 4509 | 'level, but it cannot repair the cause of the error and retry ' |
| 4510 | 'the\n' |
| 4511 | 'failing operation (except by re-entering the offending piece of ' |
| 4512 | 'code\n' |
| 4513 | 'from the top).\n' |
| 4514 | '\n' |
| 4515 | 'When an exception is not handled at all, the interpreter ' |
| 4516 | 'terminates\n' |
| 4517 | 'execution of the program, or returns to its interactive main ' |
| 4518 | 'loop. In\n' |
| 4519 | 'either case, it prints a stack backtrace, except when the ' |
| 4520 | 'exception is\n' |
| 4521 | '"SystemExit".\n' |
| 4522 | '\n' |
| 4523 | 'Exceptions are identified by class instances. The "except" ' |
| 4524 | 'clause is\n' |
| 4525 | 'selected depending on the class of the instance: it must ' |
| 4526 | 'reference the\n' |
| 4527 | 'class of the instance or a base class thereof. The instance ' |
| 4528 | 'can be\n' |
| 4529 | 'received by the handler and can carry additional information ' |
| 4530 | 'about the\n' |
| 4531 | 'exceptional condition.\n' |
| 4532 | '\n' |
| 4533 | 'Note: Exception messages are not part of the Python API. ' |
| 4534 | 'Their\n' |
| 4535 | ' contents may change from one version of Python to the next ' |
| 4536 | 'without\n' |
| 4537 | ' warning and should not be relied on by code which will run ' |
| 4538 | 'under\n' |
| 4539 | ' multiple versions of the interpreter.\n' |
| 4540 | '\n' |
| 4541 | 'See also the description of the "try" statement in section The ' |
| 4542 | 'try\n' |
| 4543 | 'statement and "raise" statement in section The raise ' |
| 4544 | 'statement.\n' |
| 4545 | '\n' |
| 4546 | '-[ Footnotes ]-\n' |
| 4547 | '\n' |
| 4548 | '[1] This limitation occurs because the code that is executed ' |
| 4549 | 'by\n' |
| 4550 | ' these operations is not available at the time the module ' |
| 4551 | 'is\n' |
| 4552 | ' compiled.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4553 | 'exprlists': 'Expression lists\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4554 | '****************\n' |
| 4555 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4556 | ' expression_list ::= expression ( "," expression )* [","]\n' |
| 4557 | ' starred_list ::= starred_item ( "," starred_item )* ' |
| 4558 | '[","]\n' |
| 4559 | ' starred_expression ::= expression | ( starred_item "," )* ' |
| 4560 | '[starred_item]\n' |
| 4561 | ' starred_item ::= expression | "*" or_expr\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4562 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 4563 | 'Except when part of a list or set display, an expression list\n' |
| 4564 | 'containing at least one comma yields a tuple. The length of ' |
| 4565 | 'the tuple\n' |
| 4566 | 'is the number of expressions in the list. The expressions are\n' |
| 4567 | 'evaluated from left to right.\n' |
| 4568 | '\n' |
| 4569 | 'An asterisk "*" denotes *iterable unpacking*. Its operand must ' |
| 4570 | 'be an\n' |
| 4571 | '*iterable*. The iterable is expanded into a sequence of items, ' |
| 4572 | 'which\n' |
| 4573 | 'are included in the new tuple, list, or set, at the site of ' |
| 4574 | 'the\n' |
| 4575 | 'unpacking.\n' |
| 4576 | '\n' |
| 4577 | 'New in version 3.5: Iterable unpacking in expression lists, ' |
| 4578 | 'originally\n' |
| 4579 | 'proposed by **PEP 448**.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4580 | '\n' |
| 4581 | 'The trailing comma is required only to create a single tuple ' |
| 4582 | '(a.k.a. a\n' |
| 4583 | '*singleton*); it is optional in all other cases. A single ' |
| 4584 | 'expression\n' |
| 4585 | "without a trailing comma doesn't create a tuple, but rather " |
| 4586 | 'yields the\n' |
| 4587 | 'value of that expression. (To create an empty tuple, use an ' |
| 4588 | 'empty pair\n' |
| 4589 | 'of parentheses: "()".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4590 | 'floating': 'Floating point literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4591 | '***********************\n' |
| 4592 | '\n' |
| 4593 | 'Floating point literals are described by the following lexical\n' |
| 4594 | 'definitions:\n' |
| 4595 | '\n' |
| 4596 | ' floatnumber ::= pointfloat | exponentfloat\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4597 | ' pointfloat ::= [digitpart] fraction | digitpart "."\n' |
| 4598 | ' exponentfloat ::= (digitpart | pointfloat) exponent\n' |
| 4599 | ' digitpart ::= digit (["_"] digit)*\n' |
| 4600 | ' fraction ::= "." digitpart\n' |
| 4601 | ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4602 | '\n' |
| 4603 | 'Note that the integer and exponent parts are always interpreted ' |
| 4604 | 'using\n' |
| 4605 | 'radix 10. For example, "077e010" is legal, and denotes the same ' |
| 4606 | 'number\n' |
| 4607 | 'as "77e10". The allowed range of floating point literals is\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4608 | 'implementation-dependent. As in integer literals, underscores ' |
| 4609 | 'are\n' |
| 4610 | 'supported for digit grouping.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4611 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4612 | 'Some examples of floating point literals:\n' |
| 4613 | '\n' |
| 4614 | ' 3.14 10. .001 1e100 3.14e-10 0e0 ' |
| 4615 | '3.14_15_93\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4616 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4617 | 'Changed in version 3.6: Underscores are now allowed for ' |
| 4618 | 'grouping\n' |
| 4619 | 'purposes in literals.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4620 | 'for': 'The "for" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4621 | '*******************\n' |
| 4622 | '\n' |
| 4623 | 'The "for" statement is used to iterate over the elements of a ' |
| 4624 | 'sequence\n' |
| 4625 | '(such as a string, tuple or list) or other iterable object:\n' |
| 4626 | '\n' |
| 4627 | ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n' |
| 4628 | ' ["else" ":" suite]\n' |
| 4629 | '\n' |
| 4630 | 'The expression list is evaluated once; it should yield an iterable\n' |
| 4631 | 'object. An iterator is created for the result of the\n' |
| 4632 | '"expression_list". The suite is then executed once for each item\n' |
| 4633 | 'provided by the iterator, in the order returned by the iterator. ' |
| 4634 | 'Each\n' |
| 4635 | 'item in turn is assigned to the target list using the standard rules\n' |
| 4636 | 'for assignments (see Assignment statements), and then the suite is\n' |
| 4637 | 'executed. When the items are exhausted (which is immediately when ' |
| 4638 | 'the\n' |
| 4639 | 'sequence is empty or an iterator raises a "StopIteration" ' |
| 4640 | 'exception),\n' |
| 4641 | 'the suite in the "else" clause, if present, is executed, and the ' |
| 4642 | 'loop\n' |
| 4643 | 'terminates.\n' |
| 4644 | '\n' |
| 4645 | 'A "break" statement executed in the first suite terminates the loop\n' |
| 4646 | 'without executing the "else" clause\'s suite. A "continue" ' |
| 4647 | 'statement\n' |
| 4648 | 'executed in the first suite skips the rest of the suite and ' |
| 4649 | 'continues\n' |
| 4650 | 'with the next item, or with the "else" clause if there is no next\n' |
| 4651 | 'item.\n' |
| 4652 | '\n' |
| 4653 | 'The for-loop makes assignments to the variables(s) in the target ' |
| 4654 | 'list.\n' |
| 4655 | 'This overwrites all previous assignments to those variables ' |
| 4656 | 'including\n' |
| 4657 | 'those made in the suite of the for-loop:\n' |
| 4658 | '\n' |
| 4659 | ' for i in range(10):\n' |
| 4660 | ' print(i)\n' |
| 4661 | ' i = 5 # this will not affect the for-loop\n' |
| 4662 | ' # because i will be overwritten with the ' |
| 4663 | 'next\n' |
| 4664 | ' # index in the range\n' |
| 4665 | '\n' |
| 4666 | 'Names in the target list are not deleted when the loop is finished,\n' |
| 4667 | 'but if the sequence is empty, they will not have been assigned to at\n' |
| 4668 | 'all by the loop. Hint: the built-in function "range()" returns an\n' |
| 4669 | 'iterator of integers suitable to emulate the effect of Pascal\'s "for ' |
| 4670 | 'i\n' |
| 4671 | ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n' |
| 4672 | '\n' |
| 4673 | 'Note: There is a subtlety when the sequence is being modified by the\n' |
| 4674 | ' loop (this can only occur for mutable sequences, i.e. lists). An\n' |
| 4675 | ' internal counter is used to keep track of which item is used next,\n' |
| 4676 | ' and this is incremented on each iteration. When this counter has\n' |
| 4677 | ' reached the length of the sequence the loop terminates. This ' |
| 4678 | 'means\n' |
| 4679 | ' that if the suite deletes the current (or a previous) item from ' |
| 4680 | 'the\n' |
| 4681 | ' sequence, the next item will be skipped (since it gets the index ' |
| 4682 | 'of\n' |
| 4683 | ' the current item which has already been treated). Likewise, if ' |
| 4684 | 'the\n' |
| 4685 | ' suite inserts an item in the sequence before the current item, the\n' |
| 4686 | ' current item will be treated again the next time through the loop.\n' |
| 4687 | ' This can lead to nasty bugs that can be avoided by making a\n' |
| 4688 | ' temporary copy using a slice of the whole sequence, e.g.,\n' |
| 4689 | '\n' |
| 4690 | ' for x in a[:]:\n' |
| 4691 | ' if x < 0: a.remove(x)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 4692 | 'formatstrings': 'Format String Syntax\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4693 | '********************\n' |
| 4694 | '\n' |
| 4695 | 'The "str.format()" method and the "Formatter" class share ' |
| 4696 | 'the same\n' |
| 4697 | 'syntax for format strings (although in the case of ' |
| 4698 | '"Formatter",\n' |
| 4699 | 'subclasses can define their own format string syntax). The ' |
| 4700 | 'syntax is\n' |
| 4701 | 'related to that of formatted string literals, but there ' |
| 4702 | 'are\n' |
| 4703 | 'differences.\n' |
| 4704 | '\n' |
| 4705 | 'Format strings contain "replacement fields" surrounded by ' |
| 4706 | 'curly braces\n' |
| 4707 | '"{}". Anything that is not contained in braces is ' |
| 4708 | 'considered literal\n' |
| 4709 | 'text, which is copied unchanged to the output. If you need ' |
| 4710 | 'to include\n' |
| 4711 | 'a brace character in the literal text, it can be escaped by ' |
| 4712 | 'doubling:\n' |
| 4713 | '"{{" and "}}".\n' |
| 4714 | '\n' |
| 4715 | 'The grammar for a replacement field is as follows:\n' |
| 4716 | '\n' |
| 4717 | ' replacement_field ::= "{" [field_name] ["!" ' |
| 4718 | 'conversion] [":" format_spec] "}"\n' |
| 4719 | ' field_name ::= arg_name ("." attribute_name | ' |
| 4720 | '"[" element_index "]")*\n' |
| 4721 | ' arg_name ::= [identifier | integer]\n' |
| 4722 | ' attribute_name ::= identifier\n' |
| 4723 | ' element_index ::= integer | index_string\n' |
| 4724 | ' index_string ::= <any source character except ' |
| 4725 | '"]"> +\n' |
| 4726 | ' conversion ::= "r" | "s" | "a"\n' |
| 4727 | ' format_spec ::= <described in the next ' |
| 4728 | 'section>\n' |
| 4729 | '\n' |
| 4730 | 'In less formal terms, the replacement field can start with ' |
| 4731 | 'a\n' |
| 4732 | '*field_name* that specifies the object whose value is to be ' |
| 4733 | 'formatted\n' |
| 4734 | 'and inserted into the output instead of the replacement ' |
| 4735 | 'field. The\n' |
| 4736 | '*field_name* is optionally followed by a *conversion* ' |
| 4737 | 'field, which is\n' |
| 4738 | 'preceded by an exclamation point "\'!\'", and a ' |
| 4739 | '*format_spec*, which is\n' |
| 4740 | 'preceded by a colon "\':\'". These specify a non-default ' |
| 4741 | 'format for the\n' |
| 4742 | 'replacement value.\n' |
| 4743 | '\n' |
| 4744 | 'See also the Format Specification Mini-Language section.\n' |
| 4745 | '\n' |
| 4746 | 'The *field_name* itself begins with an *arg_name* that is ' |
| 4747 | 'either a\n' |
| 4748 | "number or a keyword. If it's a number, it refers to a " |
| 4749 | 'positional\n' |
| 4750 | "argument, and if it's a keyword, it refers to a named " |
| 4751 | 'keyword\n' |
| 4752 | 'argument. If the numerical arg_names in a format string ' |
| 4753 | 'are 0, 1, 2,\n' |
| 4754 | '... in sequence, they can all be omitted (not just some) ' |
| 4755 | 'and the\n' |
| 4756 | 'numbers 0, 1, 2, ... will be automatically inserted in that ' |
| 4757 | 'order.\n' |
| 4758 | 'Because *arg_name* is not quote-delimited, it is not ' |
| 4759 | 'possible to\n' |
| 4760 | 'specify arbitrary dictionary keys (e.g., the strings ' |
| 4761 | '"\'10\'" or\n' |
| 4762 | '"\':-]\'") within a format string. The *arg_name* can be ' |
| 4763 | 'followed by any\n' |
| 4764 | 'number of index or attribute expressions. An expression of ' |
| 4765 | 'the form\n' |
| 4766 | '"\'.name\'" selects the named attribute using "getattr()", ' |
| 4767 | 'while an\n' |
| 4768 | 'expression of the form "\'[index]\'" does an index lookup ' |
| 4769 | 'using\n' |
| 4770 | '"__getitem__()".\n' |
| 4771 | '\n' |
| 4772 | 'Changed in version 3.1: The positional argument specifiers ' |
| 4773 | 'can be\n' |
| 4774 | 'omitted, so "\'{} {}\'" is equivalent to "\'{0} {1}\'".\n' |
| 4775 | '\n' |
| 4776 | 'Some simple format string examples:\n' |
| 4777 | '\n' |
| 4778 | ' "First, thou shalt count to {0}" # References first ' |
| 4779 | 'positional argument\n' |
| 4780 | ' "Bring me a {}" # Implicitly ' |
| 4781 | 'references the first positional argument\n' |
| 4782 | ' "From {} to {}" # Same as "From {0} to ' |
| 4783 | '{1}"\n' |
| 4784 | ' "My quest is {name}" # References keyword ' |
| 4785 | "argument 'name'\n" |
| 4786 | ' "Weight in tons {0.weight}" # \'weight\' attribute ' |
| 4787 | 'of first positional arg\n' |
| 4788 | ' "Units destroyed: {players[0]}" # First element of ' |
| 4789 | "keyword argument 'players'.\n" |
| 4790 | '\n' |
| 4791 | 'The *conversion* field causes a type coercion before ' |
| 4792 | 'formatting.\n' |
| 4793 | 'Normally, the job of formatting a value is done by the ' |
| 4794 | '"__format__()"\n' |
| 4795 | 'method of the value itself. However, in some cases it is ' |
| 4796 | 'desirable to\n' |
| 4797 | 'force a type to be formatted as a string, overriding its ' |
| 4798 | 'own\n' |
| 4799 | 'definition of formatting. By converting the value to a ' |
| 4800 | 'string before\n' |
| 4801 | 'calling "__format__()", the normal formatting logic is ' |
| 4802 | 'bypassed.\n' |
| 4803 | '\n' |
| 4804 | 'Three conversion flags are currently supported: "\'!s\'" ' |
| 4805 | 'which calls\n' |
| 4806 | '"str()" on the value, "\'!r\'" which calls "repr()" and ' |
| 4807 | '"\'!a\'" which\n' |
| 4808 | 'calls "ascii()".\n' |
| 4809 | '\n' |
| 4810 | 'Some examples:\n' |
| 4811 | '\n' |
| 4812 | ' "Harold\'s a clever {0!s}" # Calls str() on the ' |
| 4813 | 'argument first\n' |
| 4814 | ' "Bring out the holy {name!r}" # Calls repr() on the ' |
| 4815 | 'argument first\n' |
| 4816 | ' "More {!a}" # Calls ascii() on the ' |
| 4817 | 'argument first\n' |
| 4818 | '\n' |
| 4819 | 'The *format_spec* field contains a specification of how the ' |
| 4820 | 'value\n' |
| 4821 | 'should be presented, including such details as field width, ' |
| 4822 | 'alignment,\n' |
| 4823 | 'padding, decimal precision and so on. Each value type can ' |
| 4824 | 'define its\n' |
| 4825 | 'own "formatting mini-language" or interpretation of the ' |
| 4826 | '*format_spec*.\n' |
| 4827 | '\n' |
| 4828 | 'Most built-in types support a common formatting ' |
| 4829 | 'mini-language, which\n' |
| 4830 | 'is described in the next section.\n' |
| 4831 | '\n' |
| 4832 | 'A *format_spec* field can also include nested replacement ' |
| 4833 | 'fields\n' |
| 4834 | 'within it. These nested replacement fields may contain a ' |
| 4835 | 'field name,\n' |
| 4836 | 'conversion flag and format specification, but deeper ' |
| 4837 | 'nesting is not\n' |
| 4838 | 'allowed. The replacement fields within the format_spec ' |
| 4839 | 'are\n' |
| 4840 | 'substituted before the *format_spec* string is interpreted. ' |
| 4841 | 'This\n' |
| 4842 | 'allows the formatting of a value to be dynamically ' |
| 4843 | 'specified.\n' |
| 4844 | '\n' |
| 4845 | 'See the Format examples section for some examples.\n' |
| 4846 | '\n' |
| 4847 | '\n' |
| 4848 | 'Format Specification Mini-Language\n' |
| 4849 | '==================================\n' |
| 4850 | '\n' |
| 4851 | '"Format specifications" are used within replacement fields ' |
| 4852 | 'contained\n' |
| 4853 | 'within a format string to define how individual values are ' |
| 4854 | 'presented\n' |
| 4855 | '(see Format String Syntax and Formatted string literals). ' |
| 4856 | 'They can\n' |
| 4857 | 'also be passed directly to the built-in "format()" ' |
| 4858 | 'function. Each\n' |
| 4859 | 'formattable type may define how the format specification is ' |
| 4860 | 'to be\n' |
| 4861 | 'interpreted.\n' |
| 4862 | '\n' |
| 4863 | 'Most built-in types implement the following options for ' |
| 4864 | 'format\n' |
| 4865 | 'specifications, although some of the formatting options are ' |
| 4866 | 'only\n' |
| 4867 | 'supported by the numeric types.\n' |
| 4868 | '\n' |
| 4869 | 'A general convention is that an empty format string ("""") ' |
| 4870 | 'produces\n' |
| 4871 | 'the same result as if you had called "str()" on the value. ' |
| 4872 | 'A non-empty\n' |
| 4873 | 'format string typically modifies the result.\n' |
| 4874 | '\n' |
| 4875 | 'The general form of a *standard format specifier* is:\n' |
| 4876 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 4877 | ' format_spec ::= ' |
| 4878 | '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n' |
| 4879 | ' fill ::= <any character>\n' |
| 4880 | ' align ::= "<" | ">" | "=" | "^"\n' |
| 4881 | ' sign ::= "+" | "-" | " "\n' |
| 4882 | ' width ::= integer\n' |
| 4883 | ' grouping_option ::= "_" | ","\n' |
| 4884 | ' precision ::= integer\n' |
| 4885 | ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' |
| 4886 | '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 4887 | '\n' |
| 4888 | 'If a valid *align* value is specified, it can be preceded ' |
| 4889 | 'by a *fill*\n' |
| 4890 | 'character that can be any character and defaults to a space ' |
| 4891 | 'if\n' |
| 4892 | 'omitted. It is not possible to use a literal curly brace ' |
| 4893 | '(""{"" or\n' |
| 4894 | '""}"") as the *fill* character in a formatted string ' |
| 4895 | 'literal or when\n' |
| 4896 | 'using the "str.format()" method. However, it is possible ' |
| 4897 | 'to insert a\n' |
| 4898 | 'curly brace with a nested replacement field. This ' |
| 4899 | "limitation doesn't\n" |
| 4900 | 'affect the "format()" function.\n' |
| 4901 | '\n' |
| 4902 | 'The meaning of the various alignment options is as ' |
| 4903 | 'follows:\n' |
| 4904 | '\n' |
| 4905 | ' ' |
| 4906 | '+-----------+------------------------------------------------------------+\n' |
| 4907 | ' | Option | ' |
| 4908 | 'Meaning ' |
| 4909 | '|\n' |
| 4910 | ' ' |
| 4911 | '+===========+============================================================+\n' |
| 4912 | ' | "\'<\'" | Forces the field to be left-aligned ' |
| 4913 | 'within the available |\n' |
| 4914 | ' | | space (this is the default for most ' |
| 4915 | 'objects). |\n' |
| 4916 | ' ' |
| 4917 | '+-----------+------------------------------------------------------------+\n' |
| 4918 | ' | "\'>\'" | Forces the field to be right-aligned ' |
| 4919 | 'within the available |\n' |
| 4920 | ' | | space (this is the default for ' |
| 4921 | 'numbers). |\n' |
| 4922 | ' ' |
| 4923 | '+-----------+------------------------------------------------------------+\n' |
| 4924 | ' | "\'=\'" | Forces the padding to be placed after ' |
| 4925 | 'the sign (if any) |\n' |
| 4926 | ' | | but before the digits. This is used for ' |
| 4927 | 'printing fields |\n' |
| 4928 | " | | in the form '+000000120'. This alignment " |
| 4929 | 'option is only |\n' |
| 4930 | ' | | valid for numeric types. It becomes the ' |
| 4931 | "default when '0' |\n" |
| 4932 | ' | | immediately precedes the field ' |
| 4933 | 'width. |\n' |
| 4934 | ' ' |
| 4935 | '+-----------+------------------------------------------------------------+\n' |
| 4936 | ' | "\'^\'" | Forces the field to be centered within ' |
| 4937 | 'the available |\n' |
| 4938 | ' | | ' |
| 4939 | 'space. ' |
| 4940 | '|\n' |
| 4941 | ' ' |
| 4942 | '+-----------+------------------------------------------------------------+\n' |
| 4943 | '\n' |
| 4944 | 'Note that unless a minimum field width is defined, the ' |
| 4945 | 'field width\n' |
| 4946 | 'will always be the same size as the data to fill it, so ' |
| 4947 | 'that the\n' |
| 4948 | 'alignment option has no meaning in this case.\n' |
| 4949 | '\n' |
| 4950 | 'The *sign* option is only valid for number types, and can ' |
| 4951 | 'be one of\n' |
| 4952 | 'the following:\n' |
| 4953 | '\n' |
| 4954 | ' ' |
| 4955 | '+-----------+------------------------------------------------------------+\n' |
| 4956 | ' | Option | ' |
| 4957 | 'Meaning ' |
| 4958 | '|\n' |
| 4959 | ' ' |
| 4960 | '+===========+============================================================+\n' |
| 4961 | ' | "\'+\'" | indicates that a sign should be used for ' |
| 4962 | 'both positive as |\n' |
| 4963 | ' | | well as negative ' |
| 4964 | 'numbers. |\n' |
| 4965 | ' ' |
| 4966 | '+-----------+------------------------------------------------------------+\n' |
| 4967 | ' | "\'-\'" | indicates that a sign should be used ' |
| 4968 | 'only for negative |\n' |
| 4969 | ' | | numbers (this is the default ' |
| 4970 | 'behavior). |\n' |
| 4971 | ' ' |
| 4972 | '+-----------+------------------------------------------------------------+\n' |
| 4973 | ' | space | indicates that a leading space should be ' |
| 4974 | 'used on positive |\n' |
| 4975 | ' | | numbers, and a minus sign on negative ' |
| 4976 | 'numbers. |\n' |
| 4977 | ' ' |
| 4978 | '+-----------+------------------------------------------------------------+\n' |
| 4979 | '\n' |
| 4980 | 'The "\'#\'" option causes the "alternate form" to be used ' |
| 4981 | 'for the\n' |
| 4982 | 'conversion. The alternate form is defined differently for ' |
| 4983 | 'different\n' |
| 4984 | 'types. This option is only valid for integer, float, ' |
| 4985 | 'complex and\n' |
| 4986 | 'Decimal types. For integers, when binary, octal, or ' |
| 4987 | 'hexadecimal output\n' |
| 4988 | 'is used, this option adds the prefix respective "\'0b\'", ' |
| 4989 | '"\'0o\'", or\n' |
| 4990 | '"\'0x\'" to the output value. For floats, complex and ' |
| 4991 | 'Decimal the\n' |
| 4992 | 'alternate form causes the result of the conversion to ' |
| 4993 | 'always contain a\n' |
| 4994 | 'decimal-point character, even if no digits follow it. ' |
| 4995 | 'Normally, a\n' |
| 4996 | 'decimal-point character appears in the result of these ' |
| 4997 | 'conversions\n' |
| 4998 | 'only if a digit follows it. In addition, for "\'g\'" and ' |
| 4999 | '"\'G\'"\n' |
| 5000 | 'conversions, trailing zeros are not removed from the ' |
| 5001 | 'result.\n' |
| 5002 | '\n' |
| 5003 | 'The "\',\'" option signals the use of a comma for a ' |
| 5004 | 'thousands separator.\n' |
| 5005 | 'For a locale aware separator, use the "\'n\'" integer ' |
| 5006 | 'presentation type\n' |
| 5007 | 'instead.\n' |
| 5008 | '\n' |
| 5009 | 'Changed in version 3.1: Added the "\',\'" option (see also ' |
| 5010 | '**PEP 378**).\n' |
| 5011 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5012 | 'The "\'_\'" option signals the use of an underscore for a ' |
| 5013 | 'thousands\n' |
| 5014 | 'separator for floating point presentation types and for ' |
| 5015 | 'integer\n' |
| 5016 | 'presentation type "\'d\'". For integer presentation types ' |
| 5017 | '"\'b\'", "\'o\'",\n' |
| 5018 | '"\'x\'", and "\'X\'", underscores will be inserted every 4 ' |
| 5019 | 'digits. For\n' |
| 5020 | 'other presentation types, specifying this option is an ' |
| 5021 | 'error.\n' |
| 5022 | '\n' |
| 5023 | 'Changed in version 3.6: Added the "\'_\'" option (see also ' |
| 5024 | '**PEP 515**).\n' |
| 5025 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5026 | '*width* is a decimal integer defining the minimum field ' |
| 5027 | 'width. If not\n' |
| 5028 | 'specified, then the field width will be determined by the ' |
| 5029 | 'content.\n' |
| 5030 | '\n' |
| 5031 | 'When no explicit alignment is given, preceding the *width* ' |
| 5032 | 'field by a\n' |
| 5033 | 'zero ("\'0\'") character enables sign-aware zero-padding ' |
| 5034 | 'for numeric\n' |
| 5035 | 'types. This is equivalent to a *fill* character of "\'0\'" ' |
| 5036 | 'with an\n' |
| 5037 | '*alignment* type of "\'=\'".\n' |
| 5038 | '\n' |
| 5039 | 'The *precision* is a decimal number indicating how many ' |
| 5040 | 'digits should\n' |
| 5041 | 'be displayed after the decimal point for a floating point ' |
| 5042 | 'value\n' |
| 5043 | 'formatted with "\'f\'" and "\'F\'", or before and after the ' |
| 5044 | 'decimal point\n' |
| 5045 | 'for a floating point value formatted with "\'g\'" or ' |
| 5046 | '"\'G\'". For non-\n' |
| 5047 | 'number types the field indicates the maximum field size - ' |
| 5048 | 'in other\n' |
| 5049 | 'words, how many characters will be used from the field ' |
| 5050 | 'content. The\n' |
| 5051 | '*precision* is not allowed for integer values.\n' |
| 5052 | '\n' |
| 5053 | 'Finally, the *type* determines how the data should be ' |
| 5054 | 'presented.\n' |
| 5055 | '\n' |
| 5056 | 'The available string presentation types are:\n' |
| 5057 | '\n' |
| 5058 | ' ' |
| 5059 | '+-----------+------------------------------------------------------------+\n' |
| 5060 | ' | Type | ' |
| 5061 | 'Meaning ' |
| 5062 | '|\n' |
| 5063 | ' ' |
| 5064 | '+===========+============================================================+\n' |
| 5065 | ' | "\'s\'" | String format. This is the default type ' |
| 5066 | 'for strings and |\n' |
| 5067 | ' | | may be ' |
| 5068 | 'omitted. |\n' |
| 5069 | ' ' |
| 5070 | '+-----------+------------------------------------------------------------+\n' |
| 5071 | ' | None | The same as ' |
| 5072 | '"\'s\'". |\n' |
| 5073 | ' ' |
| 5074 | '+-----------+------------------------------------------------------------+\n' |
| 5075 | '\n' |
| 5076 | 'The available integer presentation types are:\n' |
| 5077 | '\n' |
| 5078 | ' ' |
| 5079 | '+-----------+------------------------------------------------------------+\n' |
| 5080 | ' | Type | ' |
| 5081 | 'Meaning ' |
| 5082 | '|\n' |
| 5083 | ' ' |
| 5084 | '+===========+============================================================+\n' |
| 5085 | ' | "\'b\'" | Binary format. Outputs the number in ' |
| 5086 | 'base 2. |\n' |
| 5087 | ' ' |
| 5088 | '+-----------+------------------------------------------------------------+\n' |
| 5089 | ' | "\'c\'" | Character. Converts the integer to the ' |
| 5090 | 'corresponding |\n' |
| 5091 | ' | | unicode character before ' |
| 5092 | 'printing. |\n' |
| 5093 | ' ' |
| 5094 | '+-----------+------------------------------------------------------------+\n' |
| 5095 | ' | "\'d\'" | Decimal Integer. Outputs the number in ' |
| 5096 | 'base 10. |\n' |
| 5097 | ' ' |
| 5098 | '+-----------+------------------------------------------------------------+\n' |
| 5099 | ' | "\'o\'" | Octal format. Outputs the number in base ' |
| 5100 | '8. |\n' |
| 5101 | ' ' |
| 5102 | '+-----------+------------------------------------------------------------+\n' |
| 5103 | ' | "\'x\'" | Hex format. Outputs the number in base ' |
| 5104 | '16, using lower- |\n' |
| 5105 | ' | | case letters for the digits above ' |
| 5106 | '9. |\n' |
| 5107 | ' ' |
| 5108 | '+-----------+------------------------------------------------------------+\n' |
| 5109 | ' | "\'X\'" | Hex format. Outputs the number in base ' |
| 5110 | '16, using upper- |\n' |
| 5111 | ' | | case letters for the digits above ' |
| 5112 | '9. |\n' |
| 5113 | ' ' |
| 5114 | '+-----------+------------------------------------------------------------+\n' |
| 5115 | ' | "\'n\'" | Number. This is the same as "\'d\'", ' |
| 5116 | 'except that it uses the |\n' |
| 5117 | ' | | current locale setting to insert the ' |
| 5118 | 'appropriate number |\n' |
| 5119 | ' | | separator ' |
| 5120 | 'characters. |\n' |
| 5121 | ' ' |
| 5122 | '+-----------+------------------------------------------------------------+\n' |
| 5123 | ' | None | The same as ' |
| 5124 | '"\'d\'". |\n' |
| 5125 | ' ' |
| 5126 | '+-----------+------------------------------------------------------------+\n' |
| 5127 | '\n' |
| 5128 | 'In addition to the above presentation types, integers can ' |
| 5129 | 'be formatted\n' |
| 5130 | 'with the floating point presentation types listed below ' |
| 5131 | '(except "\'n\'"\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5132 | 'and "None"). When doing so, "float()" is used to convert ' |
| 5133 | 'the integer\n' |
| 5134 | 'to a floating point number before formatting.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5135 | '\n' |
| 5136 | 'The available presentation types for floating point and ' |
| 5137 | 'decimal values\n' |
| 5138 | 'are:\n' |
| 5139 | '\n' |
| 5140 | ' ' |
| 5141 | '+-----------+------------------------------------------------------------+\n' |
| 5142 | ' | Type | ' |
| 5143 | 'Meaning ' |
| 5144 | '|\n' |
| 5145 | ' ' |
| 5146 | '+===========+============================================================+\n' |
| 5147 | ' | "\'e\'" | Exponent notation. Prints the number in ' |
| 5148 | 'scientific |\n' |
| 5149 | " | | notation using the letter 'e' to indicate " |
| 5150 | 'the exponent. |\n' |
| 5151 | ' | | The default precision is ' |
| 5152 | '"6". |\n' |
| 5153 | ' ' |
| 5154 | '+-----------+------------------------------------------------------------+\n' |
| 5155 | ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' |
| 5156 | 'except it uses an upper |\n' |
| 5157 | " | | case 'E' as the separator " |
| 5158 | 'character. |\n' |
| 5159 | ' ' |
| 5160 | '+-----------+------------------------------------------------------------+\n' |
| 5161 | ' | "\'f\'" | Fixed point. Displays the number as a ' |
| 5162 | 'fixed-point number. |\n' |
| 5163 | ' | | The default precision is ' |
| 5164 | '"6". |\n' |
| 5165 | ' ' |
| 5166 | '+-----------+------------------------------------------------------------+\n' |
| 5167 | ' | "\'F\'" | Fixed point. Same as "\'f\'", but ' |
| 5168 | 'converts "nan" to "NAN" |\n' |
| 5169 | ' | | and "inf" to ' |
| 5170 | '"INF". |\n' |
| 5171 | ' ' |
| 5172 | '+-----------+------------------------------------------------------------+\n' |
| 5173 | ' | "\'g\'" | General format. For a given precision ' |
| 5174 | '"p >= 1", this |\n' |
| 5175 | ' | | rounds the number to "p" significant ' |
| 5176 | 'digits and then |\n' |
| 5177 | ' | | formats the result in either fixed-point ' |
| 5178 | 'format or in |\n' |
| 5179 | ' | | scientific notation, depending on its ' |
| 5180 | 'magnitude. The |\n' |
| 5181 | ' | | precise rules are as follows: suppose that ' |
| 5182 | 'the result |\n' |
| 5183 | ' | | formatted with presentation type "\'e\'" ' |
| 5184 | 'and precision "p-1" |\n' |
| 5185 | ' | | would have exponent "exp". Then if "-4 <= ' |
| 5186 | 'exp < p", the |\n' |
| 5187 | ' | | number is formatted with presentation type ' |
| 5188 | '"\'f\'" and |\n' |
| 5189 | ' | | precision "p-1-exp". Otherwise, the ' |
| 5190 | 'number is formatted |\n' |
| 5191 | ' | | with presentation type "\'e\'" and ' |
| 5192 | 'precision "p-1". In both |\n' |
| 5193 | ' | | cases insignificant trailing zeros are ' |
| 5194 | 'removed from the |\n' |
| 5195 | ' | | significand, and the decimal point is also ' |
| 5196 | 'removed if |\n' |
| 5197 | ' | | there are no remaining digits following ' |
| 5198 | 'it. Positive and |\n' |
| 5199 | ' | | negative infinity, positive and negative ' |
| 5200 | 'zero, and nans, |\n' |
| 5201 | ' | | are formatted as "inf", "-inf", "0", "-0" ' |
| 5202 | 'and "nan" |\n' |
| 5203 | ' | | respectively, regardless of the ' |
| 5204 | 'precision. A precision of |\n' |
| 5205 | ' | | "0" is treated as equivalent to a ' |
| 5206 | 'precision of "1". The |\n' |
| 5207 | ' | | default precision is ' |
| 5208 | '"6". |\n' |
| 5209 | ' ' |
| 5210 | '+-----------+------------------------------------------------------------+\n' |
| 5211 | ' | "\'G\'" | General format. Same as "\'g\'" except ' |
| 5212 | 'switches to "\'E\'" if |\n' |
| 5213 | ' | | the number gets too large. The ' |
| 5214 | 'representations of infinity |\n' |
| 5215 | ' | | and NaN are uppercased, ' |
| 5216 | 'too. |\n' |
| 5217 | ' ' |
| 5218 | '+-----------+------------------------------------------------------------+\n' |
| 5219 | ' | "\'n\'" | Number. This is the same as "\'g\'", ' |
| 5220 | 'except that it uses the |\n' |
| 5221 | ' | | current locale setting to insert the ' |
| 5222 | 'appropriate number |\n' |
| 5223 | ' | | separator ' |
| 5224 | 'characters. |\n' |
| 5225 | ' ' |
| 5226 | '+-----------+------------------------------------------------------------+\n' |
| 5227 | ' | "\'%\'" | Percentage. Multiplies the number by 100 ' |
| 5228 | 'and displays in |\n' |
| 5229 | ' | | fixed ("\'f\'") format, followed by a ' |
| 5230 | 'percent sign. |\n' |
| 5231 | ' ' |
| 5232 | '+-----------+------------------------------------------------------------+\n' |
| 5233 | ' | None | Similar to "\'g\'", except that ' |
| 5234 | 'fixed-point notation, when |\n' |
| 5235 | ' | | used, has at least one digit past the ' |
| 5236 | 'decimal point. The |\n' |
| 5237 | ' | | default precision is as high as needed to ' |
| 5238 | 'represent the |\n' |
| 5239 | ' | | particular value. The overall effect is to ' |
| 5240 | 'match the |\n' |
| 5241 | ' | | output of "str()" as altered by the other ' |
| 5242 | 'format |\n' |
| 5243 | ' | | ' |
| 5244 | 'modifiers. ' |
| 5245 | '|\n' |
| 5246 | ' ' |
| 5247 | '+-----------+------------------------------------------------------------+\n' |
| 5248 | '\n' |
| 5249 | '\n' |
| 5250 | 'Format examples\n' |
| 5251 | '===============\n' |
| 5252 | '\n' |
| 5253 | 'This section contains examples of the "str.format()" syntax ' |
| 5254 | 'and\n' |
| 5255 | 'comparison with the old "%"-formatting.\n' |
| 5256 | '\n' |
| 5257 | 'In most of the cases the syntax is similar to the old ' |
| 5258 | '"%"-formatting,\n' |
| 5259 | 'with the addition of the "{}" and with ":" used instead of ' |
| 5260 | '"%". For\n' |
| 5261 | 'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n' |
| 5262 | '\n' |
| 5263 | 'The new format syntax also supports new and different ' |
| 5264 | 'options, shown\n' |
| 5265 | 'in the follow examples.\n' |
| 5266 | '\n' |
| 5267 | 'Accessing arguments by position:\n' |
| 5268 | '\n' |
| 5269 | " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" |
| 5270 | " 'a, b, c'\n" |
| 5271 | " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" |
| 5272 | " 'a, b, c'\n" |
| 5273 | " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" |
| 5274 | " 'c, b, a'\n" |
| 5275 | " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking " |
| 5276 | 'argument sequence\n' |
| 5277 | " 'c, b, a'\n" |
| 5278 | " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' " |
| 5279 | 'indices can be repeated\n' |
| 5280 | " 'abracadabra'\n" |
| 5281 | '\n' |
| 5282 | 'Accessing arguments by name:\n' |
| 5283 | '\n' |
| 5284 | " >>> 'Coordinates: {latitude}, " |
| 5285 | "{longitude}'.format(latitude='37.24N', " |
| 5286 | "longitude='-115.81W')\n" |
| 5287 | " 'Coordinates: 37.24N, -115.81W'\n" |
| 5288 | " >>> coord = {'latitude': '37.24N', 'longitude': " |
| 5289 | "'-115.81W'}\n" |
| 5290 | " >>> 'Coordinates: {latitude}, " |
| 5291 | "{longitude}'.format(**coord)\n" |
| 5292 | " 'Coordinates: 37.24N, -115.81W'\n" |
| 5293 | '\n' |
| 5294 | "Accessing arguments' attributes:\n" |
| 5295 | '\n' |
| 5296 | ' >>> c = 3-5j\n' |
| 5297 | " >>> ('The complex number {0} is formed from the real " |
| 5298 | "part {0.real} '\n" |
| 5299 | " ... 'and the imaginary part {0.imag}.').format(c)\n" |
| 5300 | " 'The complex number (3-5j) is formed from the real part " |
| 5301 | "3.0 and the imaginary part -5.0.'\n" |
| 5302 | ' >>> class Point:\n' |
| 5303 | ' ... def __init__(self, x, y):\n' |
| 5304 | ' ... self.x, self.y = x, y\n' |
| 5305 | ' ... def __str__(self):\n' |
| 5306 | " ... return 'Point({self.x}, " |
| 5307 | "{self.y})'.format(self=self)\n" |
| 5308 | ' ...\n' |
| 5309 | ' >>> str(Point(4, 2))\n' |
| 5310 | " 'Point(4, 2)'\n" |
| 5311 | '\n' |
| 5312 | "Accessing arguments' items:\n" |
| 5313 | '\n' |
| 5314 | ' >>> coord = (3, 5)\n' |
| 5315 | " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" |
| 5316 | " 'X: 3; Y: 5'\n" |
| 5317 | '\n' |
| 5318 | 'Replacing "%s" and "%r":\n' |
| 5319 | '\n' |
| 5320 | ' >>> "repr() shows quotes: {!r}; str() doesn\'t: ' |
| 5321 | '{!s}".format(\'test1\', \'test2\')\n' |
| 5322 | ' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n' |
| 5323 | '\n' |
| 5324 | 'Aligning the text and specifying a width:\n' |
| 5325 | '\n' |
| 5326 | " >>> '{:<30}'.format('left aligned')\n" |
| 5327 | " 'left aligned '\n" |
| 5328 | " >>> '{:>30}'.format('right aligned')\n" |
| 5329 | " ' right aligned'\n" |
| 5330 | " >>> '{:^30}'.format('centered')\n" |
| 5331 | " ' centered '\n" |
| 5332 | " >>> '{:*^30}'.format('centered') # use '*' as a fill " |
| 5333 | 'char\n' |
| 5334 | " '***********centered***********'\n" |
| 5335 | '\n' |
| 5336 | 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n' |
| 5337 | '\n' |
| 5338 | " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it " |
| 5339 | 'always\n' |
| 5340 | " '+3.140000; -3.140000'\n" |
| 5341 | " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space " |
| 5342 | 'for positive numbers\n' |
| 5343 | " ' 3.140000; -3.140000'\n" |
| 5344 | " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the " |
| 5345 | "minus -- same as '{:f}; {:f}'\n" |
| 5346 | " '3.140000; -3.140000'\n" |
| 5347 | '\n' |
| 5348 | 'Replacing "%x" and "%o" and converting the value to ' |
| 5349 | 'different bases:\n' |
| 5350 | '\n' |
| 5351 | ' >>> # format also supports binary numbers\n' |
| 5352 | ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: ' |
| 5353 | '{0:b}".format(42)\n' |
| 5354 | " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n" |
| 5355 | ' >>> # with 0x, 0o, or 0b as prefix:\n' |
| 5356 | ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: ' |
| 5357 | '{0:#b}".format(42)\n' |
| 5358 | " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n" |
| 5359 | '\n' |
| 5360 | 'Using the comma as a thousands separator:\n' |
| 5361 | '\n' |
| 5362 | " >>> '{:,}'.format(1234567890)\n" |
| 5363 | " '1,234,567,890'\n" |
| 5364 | '\n' |
| 5365 | 'Expressing a percentage:\n' |
| 5366 | '\n' |
| 5367 | ' >>> points = 19\n' |
| 5368 | ' >>> total = 22\n' |
| 5369 | " >>> 'Correct answers: {:.2%}'.format(points/total)\n" |
| 5370 | " 'Correct answers: 86.36%'\n" |
| 5371 | '\n' |
| 5372 | 'Using type-specific formatting:\n' |
| 5373 | '\n' |
| 5374 | ' >>> import datetime\n' |
| 5375 | ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n' |
| 5376 | " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n" |
| 5377 | " '2010-07-04 12:15:58'\n" |
| 5378 | '\n' |
| 5379 | 'Nesting arguments and more complex examples:\n' |
| 5380 | '\n' |
| 5381 | " >>> for align, text in zip('<^>', ['left', 'center', " |
| 5382 | "'right']):\n" |
| 5383 | " ... '{0:{fill}{align}16}'.format(text, fill=align, " |
| 5384 | 'align=align)\n' |
| 5385 | ' ...\n' |
| 5386 | " 'left<<<<<<<<<<<<'\n" |
| 5387 | " '^^^^^center^^^^^'\n" |
| 5388 | " '>>>>>>>>>>>right'\n" |
| 5389 | ' >>>\n' |
| 5390 | ' >>> octets = [192, 168, 0, 1]\n' |
| 5391 | " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n" |
| 5392 | " 'C0A80001'\n" |
| 5393 | ' >>> int(_, 16)\n' |
| 5394 | ' 3232235521\n' |
| 5395 | ' >>>\n' |
| 5396 | ' >>> width = 5\n' |
| 5397 | ' >>> for num in range(5,12): #doctest: ' |
| 5398 | '+NORMALIZE_WHITESPACE\n' |
| 5399 | " ... for base in 'dXob':\n" |
| 5400 | " ... print('{0:{width}{base}}'.format(num, " |
| 5401 | "base=base, width=width), end=' ')\n" |
| 5402 | ' ... print()\n' |
| 5403 | ' ...\n' |
| 5404 | ' 5 5 5 101\n' |
| 5405 | ' 6 6 6 110\n' |
| 5406 | ' 7 7 7 111\n' |
| 5407 | ' 8 8 10 1000\n' |
| 5408 | ' 9 9 11 1001\n' |
| 5409 | ' 10 A 12 1010\n' |
| 5410 | ' 11 B 13 1011\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5411 | 'function': 'Function definitions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5412 | '********************\n' |
| 5413 | '\n' |
| 5414 | 'A function definition defines a user-defined function object ' |
| 5415 | '(see\n' |
| 5416 | 'section The standard type hierarchy):\n' |
| 5417 | '\n' |
| 5418 | ' funcdef ::= [decorators] "def" funcname "(" ' |
| 5419 | '[parameter_list] ")" ["->" expression] ":" suite\n' |
| 5420 | ' decorators ::= decorator+\n' |
| 5421 | ' decorator ::= "@" dotted_name ["(" ' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 5422 | '[argument_list [","]] ")"] NEWLINE\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5423 | ' dotted_name ::= identifier ("." identifier)*\n' |
| 5424 | ' parameter_list ::= defparameter ("," defparameter)* ' |
| 5425 | '["," [parameter_list_starargs]]\n' |
| 5426 | ' | parameter_list_starargs\n' |
| 5427 | ' parameter_list_starargs ::= "*" [parameter] ("," ' |
| 5428 | 'defparameter)* ["," ["**" parameter [","]]]\n' |
| 5429 | ' | "**" parameter [","]\n' |
| 5430 | ' parameter ::= identifier [":" expression]\n' |
| 5431 | ' defparameter ::= parameter ["=" expression]\n' |
| 5432 | ' funcname ::= identifier\n' |
| 5433 | '\n' |
| 5434 | 'A function definition is an executable statement. Its execution ' |
| 5435 | 'binds\n' |
| 5436 | 'the function name in the current local namespace to a function ' |
| 5437 | 'object\n' |
| 5438 | '(a wrapper around the executable code for the function). This\n' |
| 5439 | 'function object contains a reference to the current global ' |
| 5440 | 'namespace\n' |
| 5441 | 'as the global namespace to be used when the function is called.\n' |
| 5442 | '\n' |
| 5443 | 'The function definition does not execute the function body; this ' |
| 5444 | 'gets\n' |
| 5445 | 'executed only when the function is called. [3]\n' |
| 5446 | '\n' |
| 5447 | 'A function definition may be wrapped by one or more *decorator*\n' |
| 5448 | 'expressions. Decorator expressions are evaluated when the ' |
| 5449 | 'function is\n' |
| 5450 | 'defined, in the scope that contains the function definition. ' |
| 5451 | 'The\n' |
| 5452 | 'result must be a callable, which is invoked with the function ' |
| 5453 | 'object\n' |
| 5454 | 'as the only argument. The returned value is bound to the ' |
| 5455 | 'function name\n' |
| 5456 | 'instead of the function object. Multiple decorators are applied ' |
| 5457 | 'in\n' |
| 5458 | 'nested fashion. For example, the following code\n' |
| 5459 | '\n' |
| 5460 | ' @f1(arg)\n' |
| 5461 | ' @f2\n' |
| 5462 | ' def func(): pass\n' |
| 5463 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 5464 | 'is roughly equivalent to\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5465 | '\n' |
| 5466 | ' def func(): pass\n' |
| 5467 | ' func = f1(arg)(f2(func))\n' |
| 5468 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 5469 | 'except that the original function is not temporarily bound to ' |
| 5470 | 'the name\n' |
| 5471 | '"func".\n' |
| 5472 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5473 | 'When one or more *parameters* have the form *parameter* "="\n' |
| 5474 | '*expression*, the function is said to have "default parameter ' |
| 5475 | 'values."\n' |
| 5476 | 'For a parameter with a default value, the corresponding ' |
| 5477 | '*argument* may\n' |
| 5478 | "be omitted from a call, in which case the parameter's default " |
| 5479 | 'value is\n' |
| 5480 | 'substituted. If a parameter has a default value, all following\n' |
| 5481 | 'parameters up until the ""*"" must also have a default value --- ' |
| 5482 | 'this\n' |
| 5483 | 'is a syntactic restriction that is not expressed by the ' |
| 5484 | 'grammar.\n' |
| 5485 | '\n' |
| 5486 | '**Default parameter values are evaluated from left to right when ' |
| 5487 | 'the\n' |
| 5488 | 'function definition is executed.** This means that the ' |
| 5489 | 'expression is\n' |
| 5490 | 'evaluated once, when the function is defined, and that the same ' |
| 5491 | '"pre-\n' |
| 5492 | 'computed" value is used for each call. This is especially ' |
| 5493 | 'important\n' |
| 5494 | 'to understand when a default parameter is a mutable object, such ' |
| 5495 | 'as a\n' |
| 5496 | 'list or a dictionary: if the function modifies the object (e.g. ' |
| 5497 | 'by\n' |
| 5498 | 'appending an item to a list), the default value is in effect ' |
| 5499 | 'modified.\n' |
| 5500 | 'This is generally not what was intended. A way around this is ' |
| 5501 | 'to use\n' |
| 5502 | '"None" as the default, and explicitly test for it in the body of ' |
| 5503 | 'the\n' |
| 5504 | 'function, e.g.:\n' |
| 5505 | '\n' |
| 5506 | ' def whats_on_the_telly(penguin=None):\n' |
| 5507 | ' if penguin is None:\n' |
| 5508 | ' penguin = []\n' |
| 5509 | ' penguin.append("property of the zoo")\n' |
| 5510 | ' return penguin\n' |
| 5511 | '\n' |
| 5512 | 'Function call semantics are described in more detail in section ' |
| 5513 | 'Calls.\n' |
| 5514 | 'A function call always assigns values to all parameters ' |
| 5515 | 'mentioned in\n' |
| 5516 | 'the parameter list, either from position arguments, from ' |
| 5517 | 'keyword\n' |
| 5518 | 'arguments, or from default values. If the form ""*identifier"" ' |
| 5519 | 'is\n' |
| 5520 | 'present, it is initialized to a tuple receiving any excess ' |
| 5521 | 'positional\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5522 | 'parameters, defaulting to the empty tuple. If the form\n' |
| 5523 | '""**identifier"" is present, it is initialized to a new ordered\n' |
| 5524 | 'mapping receiving any excess keyword arguments, defaulting to a ' |
| 5525 | 'new\n' |
| 5526 | 'empty mapping of the same type. Parameters after ""*"" or\n' |
| 5527 | '""*identifier"" are keyword-only parameters and may only be ' |
| 5528 | 'passed\n' |
| 5529 | 'used keyword arguments.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5530 | '\n' |
| 5531 | 'Parameters may have annotations of the form "": expression"" ' |
| 5532 | 'following\n' |
| 5533 | 'the parameter name. Any parameter may have an annotation even ' |
| 5534 | 'those\n' |
| 5535 | 'of the form "*identifier" or "**identifier". Functions may ' |
| 5536 | 'have\n' |
| 5537 | '"return" annotation of the form ""-> expression"" after the ' |
| 5538 | 'parameter\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 5539 | 'list. These annotations can be any valid Python expression. ' |
| 5540 | 'The\n' |
| 5541 | 'presence of annotations does not change the semantics of a ' |
| 5542 | 'function.\n' |
| 5543 | 'The annotation values are available as values of a dictionary ' |
| 5544 | 'keyed by\n' |
| 5545 | 'the parameters\' names in the "__annotations__" attribute of ' |
| 5546 | 'the\n' |
| 5547 | 'function object. If the "annotations" import from "__future__" ' |
| 5548 | 'is\n' |
| 5549 | 'used, annotations are preserved as strings at runtime which ' |
| 5550 | 'enables\n' |
| 5551 | 'postponed evaluation. Otherwise, they are evaluated when the ' |
| 5552 | 'function\n' |
| 5553 | 'definition is executed. In this case annotations may be ' |
| 5554 | 'evaluated in\n' |
| 5555 | 'a different order than they appear in the source code.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5556 | '\n' |
| 5557 | 'It is also possible to create anonymous functions (functions not ' |
| 5558 | 'bound\n' |
| 5559 | 'to a name), for immediate use in expressions. This uses lambda\n' |
| 5560 | 'expressions, described in section Lambdas. Note that the ' |
| 5561 | 'lambda\n' |
| 5562 | 'expression is merely a shorthand for a simplified function ' |
| 5563 | 'definition;\n' |
| 5564 | 'a function defined in a ""def"" statement can be passed around ' |
| 5565 | 'or\n' |
| 5566 | 'assigned to another name just like a function defined by a ' |
| 5567 | 'lambda\n' |
| 5568 | 'expression. The ""def"" form is actually more powerful since ' |
| 5569 | 'it\n' |
| 5570 | 'allows the execution of multiple statements and annotations.\n' |
| 5571 | '\n' |
| 5572 | "**Programmer's note:** Functions are first-class objects. A " |
| 5573 | '""def""\n' |
| 5574 | 'statement executed inside a function definition defines a local\n' |
| 5575 | 'function that can be returned or passed around. Free variables ' |
| 5576 | 'used\n' |
| 5577 | 'in the nested function can access the local variables of the ' |
| 5578 | 'function\n' |
| 5579 | 'containing the def. See section Naming and binding for ' |
| 5580 | 'details.\n' |
| 5581 | '\n' |
| 5582 | 'See also:\n' |
| 5583 | '\n' |
| 5584 | ' **PEP 3107** - Function Annotations\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 5585 | ' The original specification for function annotations.\n' |
| 5586 | '\n' |
| 5587 | ' **PEP 484** - Type Hints\n' |
| 5588 | ' Definition of a standard meaning for annotations: type ' |
| 5589 | 'hints.\n' |
| 5590 | '\n' |
| 5591 | ' **PEP 526** - Syntax for Variable Annotations\n' |
| 5592 | ' Ability to type hint variable declarations, including ' |
| 5593 | 'class\n' |
| 5594 | ' variables and instance variables\n' |
| 5595 | '\n' |
| 5596 | ' **PEP 563** - Postponed Evaluation of Annotations\n' |
| 5597 | ' Support for forward references within annotations by ' |
| 5598 | 'preserving\n' |
| 5599 | ' annotations in a string form at runtime instead of eager\n' |
| 5600 | ' evaluation.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5601 | 'global': 'The "global" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5602 | '**********************\n' |
| 5603 | '\n' |
| 5604 | ' global_stmt ::= "global" identifier ("," identifier)*\n' |
| 5605 | '\n' |
| 5606 | 'The "global" statement is a declaration which holds for the ' |
| 5607 | 'entire\n' |
| 5608 | 'current code block. It means that the listed identifiers are to ' |
| 5609 | 'be\n' |
| 5610 | 'interpreted as globals. It would be impossible to assign to a ' |
| 5611 | 'global\n' |
| 5612 | 'variable without "global", although free variables may refer to\n' |
| 5613 | 'globals without being declared global.\n' |
| 5614 | '\n' |
| 5615 | 'Names listed in a "global" statement must not be used in the same ' |
| 5616 | 'code\n' |
| 5617 | 'block textually preceding that "global" statement.\n' |
| 5618 | '\n' |
| 5619 | 'Names listed in a "global" statement must not be defined as ' |
| 5620 | 'formal\n' |
| 5621 | 'parameters or in a "for" loop control target, "class" definition,\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5622 | 'function definition, "import" statement, or variable annotation.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5623 | '\n' |
| 5624 | '**CPython implementation detail:** The current implementation does ' |
| 5625 | 'not\n' |
Ned Deily | c730223 | 2017-10-16 23:41:55 -0400 | [diff] [blame] | 5626 | 'enforce some of these restrictions, but programs should not abuse ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5627 | 'this\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5628 | 'freedom, as future implementations may enforce them or silently ' |
| 5629 | 'change\n' |
| 5630 | 'the meaning of the program.\n' |
| 5631 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5632 | '**Programmer\'s note:** "global" is a directive to the parser. ' |
| 5633 | 'It\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5634 | 'applies only to code parsed at the same time as the "global"\n' |
| 5635 | 'statement. In particular, a "global" statement contained in a ' |
| 5636 | 'string\n' |
| 5637 | 'or code object supplied to the built-in "exec()" function does ' |
| 5638 | 'not\n' |
| 5639 | 'affect the code block *containing* the function call, and code\n' |
| 5640 | 'contained in such a string is unaffected by "global" statements in ' |
| 5641 | 'the\n' |
| 5642 | 'code containing the function call. The same applies to the ' |
| 5643 | '"eval()"\n' |
| 5644 | 'and "compile()" functions.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5645 | 'id-classes': 'Reserved classes of identifiers\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5646 | '*******************************\n' |
| 5647 | '\n' |
| 5648 | 'Certain classes of identifiers (besides keywords) have ' |
| 5649 | 'special\n' |
| 5650 | 'meanings. These classes are identified by the patterns of ' |
| 5651 | 'leading and\n' |
| 5652 | 'trailing underscore characters:\n' |
| 5653 | '\n' |
| 5654 | '"_*"\n' |
| 5655 | ' Not imported by "from module import *". The special ' |
| 5656 | 'identifier "_"\n' |
| 5657 | ' is used in the interactive interpreter to store the result ' |
| 5658 | 'of the\n' |
| 5659 | ' last evaluation; it is stored in the "builtins" module. ' |
| 5660 | 'When not\n' |
| 5661 | ' in interactive mode, "_" has no special meaning and is not ' |
| 5662 | 'defined.\n' |
| 5663 | ' See section The import statement.\n' |
| 5664 | '\n' |
| 5665 | ' Note: The name "_" is often used in conjunction with\n' |
| 5666 | ' internationalization; refer to the documentation for the\n' |
| 5667 | ' "gettext" module for more information on this ' |
| 5668 | 'convention.\n' |
| 5669 | '\n' |
| 5670 | '"__*__"\n' |
| 5671 | ' System-defined names. These names are defined by the ' |
| 5672 | 'interpreter\n' |
| 5673 | ' and its implementation (including the standard library). ' |
| 5674 | 'Current\n' |
| 5675 | ' system names are discussed in the Special method names ' |
| 5676 | 'section and\n' |
| 5677 | ' elsewhere. More will likely be defined in future versions ' |
| 5678 | 'of\n' |
| 5679 | ' Python. *Any* use of "__*__" names, in any context, that ' |
| 5680 | 'does not\n' |
| 5681 | ' follow explicitly documented use, is subject to breakage ' |
| 5682 | 'without\n' |
| 5683 | ' warning.\n' |
| 5684 | '\n' |
| 5685 | '"__*"\n' |
| 5686 | ' Class-private names. Names in this category, when used ' |
| 5687 | 'within the\n' |
| 5688 | ' context of a class definition, are re-written to use a ' |
| 5689 | 'mangled form\n' |
| 5690 | ' to help avoid name clashes between "private" attributes of ' |
| 5691 | 'base and\n' |
| 5692 | ' derived classes. See section Identifiers (Names).\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5693 | 'identifiers': 'Identifiers and keywords\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5694 | '************************\n' |
| 5695 | '\n' |
| 5696 | 'Identifiers (also referred to as *names*) are described by ' |
| 5697 | 'the\n' |
| 5698 | 'following lexical definitions.\n' |
| 5699 | '\n' |
| 5700 | 'The syntax of identifiers in Python is based on the Unicode ' |
| 5701 | 'standard\n' |
| 5702 | 'annex UAX-31, with elaboration and changes as defined below; ' |
| 5703 | 'see also\n' |
| 5704 | '**PEP 3131** for further details.\n' |
| 5705 | '\n' |
| 5706 | 'Within the ASCII range (U+0001..U+007F), the valid characters ' |
| 5707 | 'for\n' |
| 5708 | 'identifiers are the same as in Python 2.x: the uppercase and ' |
| 5709 | 'lowercase\n' |
| 5710 | 'letters "A" through "Z", the underscore "_" and, except for ' |
| 5711 | 'the first\n' |
| 5712 | 'character, the digits "0" through "9".\n' |
| 5713 | '\n' |
| 5714 | 'Python 3.0 introduces additional characters from outside the ' |
| 5715 | 'ASCII\n' |
| 5716 | 'range (see **PEP 3131**). For these characters, the ' |
| 5717 | 'classification\n' |
| 5718 | 'uses the version of the Unicode Character Database as ' |
| 5719 | 'included in the\n' |
| 5720 | '"unicodedata" module.\n' |
| 5721 | '\n' |
| 5722 | 'Identifiers are unlimited in length. Case is significant.\n' |
| 5723 | '\n' |
| 5724 | ' identifier ::= xid_start xid_continue*\n' |
| 5725 | ' id_start ::= <all characters in general categories Lu, ' |
| 5726 | 'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the ' |
| 5727 | 'Other_ID_Start property>\n' |
| 5728 | ' id_continue ::= <all characters in id_start, plus ' |
| 5729 | 'characters in the categories Mn, Mc, Nd, Pc and others with ' |
| 5730 | 'the Other_ID_Continue property>\n' |
| 5731 | ' xid_start ::= <all characters in id_start whose NFKC ' |
| 5732 | 'normalization is in "id_start xid_continue*">\n' |
| 5733 | ' xid_continue ::= <all characters in id_continue whose NFKC ' |
| 5734 | 'normalization is in "id_continue*">\n' |
| 5735 | '\n' |
| 5736 | 'The Unicode category codes mentioned above stand for:\n' |
| 5737 | '\n' |
| 5738 | '* *Lu* - uppercase letters\n' |
| 5739 | '\n' |
| 5740 | '* *Ll* - lowercase letters\n' |
| 5741 | '\n' |
| 5742 | '* *Lt* - titlecase letters\n' |
| 5743 | '\n' |
| 5744 | '* *Lm* - modifier letters\n' |
| 5745 | '\n' |
| 5746 | '* *Lo* - other letters\n' |
| 5747 | '\n' |
| 5748 | '* *Nl* - letter numbers\n' |
| 5749 | '\n' |
| 5750 | '* *Mn* - nonspacing marks\n' |
| 5751 | '\n' |
| 5752 | '* *Mc* - spacing combining marks\n' |
| 5753 | '\n' |
| 5754 | '* *Nd* - decimal numbers\n' |
| 5755 | '\n' |
| 5756 | '* *Pc* - connector punctuations\n' |
| 5757 | '\n' |
| 5758 | '* *Other_ID_Start* - explicit list of characters in ' |
| 5759 | 'PropList.txt to\n' |
| 5760 | ' support backwards compatibility\n' |
| 5761 | '\n' |
| 5762 | '* *Other_ID_Continue* - likewise\n' |
| 5763 | '\n' |
| 5764 | 'All identifiers are converted into the normal form NFKC while ' |
| 5765 | 'parsing;\n' |
| 5766 | 'comparison of identifiers is based on NFKC.\n' |
| 5767 | '\n' |
| 5768 | 'A non-normative HTML file listing all valid identifier ' |
| 5769 | 'characters for\n' |
| 5770 | 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n' |
| 5771 | 'potsdam.de/home/loewis/table-3131.html.\n' |
| 5772 | '\n' |
| 5773 | '\n' |
| 5774 | 'Keywords\n' |
| 5775 | '========\n' |
| 5776 | '\n' |
| 5777 | 'The following identifiers are used as reserved words, or ' |
| 5778 | '*keywords* of\n' |
| 5779 | 'the language, and cannot be used as ordinary identifiers. ' |
| 5780 | 'They must\n' |
| 5781 | 'be spelled exactly as written here:\n' |
| 5782 | '\n' |
Ned Deily | 3f9a728 | 2017-12-05 03:17:33 -0500 | [diff] [blame] | 5783 | ' False await else import pass\n' |
| 5784 | ' None break except in raise\n' |
| 5785 | ' True class finally is return\n' |
| 5786 | ' and continue for lambda try\n' |
| 5787 | ' as def from nonlocal while\n' |
| 5788 | ' assert del global not with\n' |
| 5789 | ' async elif if or yield\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5790 | '\n' |
| 5791 | '\n' |
| 5792 | 'Reserved classes of identifiers\n' |
| 5793 | '===============================\n' |
| 5794 | '\n' |
| 5795 | 'Certain classes of identifiers (besides keywords) have ' |
| 5796 | 'special\n' |
| 5797 | 'meanings. These classes are identified by the patterns of ' |
| 5798 | 'leading and\n' |
| 5799 | 'trailing underscore characters:\n' |
| 5800 | '\n' |
| 5801 | '"_*"\n' |
| 5802 | ' Not imported by "from module import *". The special ' |
| 5803 | 'identifier "_"\n' |
| 5804 | ' is used in the interactive interpreter to store the result ' |
| 5805 | 'of the\n' |
| 5806 | ' last evaluation; it is stored in the "builtins" module. ' |
| 5807 | 'When not\n' |
| 5808 | ' in interactive mode, "_" has no special meaning and is not ' |
| 5809 | 'defined.\n' |
| 5810 | ' See section The import statement.\n' |
| 5811 | '\n' |
| 5812 | ' Note: The name "_" is often used in conjunction with\n' |
| 5813 | ' internationalization; refer to the documentation for ' |
| 5814 | 'the\n' |
| 5815 | ' "gettext" module for more information on this ' |
| 5816 | 'convention.\n' |
| 5817 | '\n' |
| 5818 | '"__*__"\n' |
| 5819 | ' System-defined names. These names are defined by the ' |
| 5820 | 'interpreter\n' |
| 5821 | ' and its implementation (including the standard library). ' |
| 5822 | 'Current\n' |
| 5823 | ' system names are discussed in the Special method names ' |
| 5824 | 'section and\n' |
| 5825 | ' elsewhere. More will likely be defined in future versions ' |
| 5826 | 'of\n' |
| 5827 | ' Python. *Any* use of "__*__" names, in any context, that ' |
| 5828 | 'does not\n' |
| 5829 | ' follow explicitly documented use, is subject to breakage ' |
| 5830 | 'without\n' |
| 5831 | ' warning.\n' |
| 5832 | '\n' |
| 5833 | '"__*"\n' |
| 5834 | ' Class-private names. Names in this category, when used ' |
| 5835 | 'within the\n' |
| 5836 | ' context of a class definition, are re-written to use a ' |
| 5837 | 'mangled form\n' |
| 5838 | ' to help avoid name clashes between "private" attributes of ' |
| 5839 | 'base and\n' |
| 5840 | ' derived classes. See section Identifiers (Names).\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5841 | 'if': 'The "if" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5842 | '******************\n' |
| 5843 | '\n' |
| 5844 | 'The "if" statement is used for conditional execution:\n' |
| 5845 | '\n' |
| 5846 | ' if_stmt ::= "if" expression ":" suite\n' |
| 5847 | ' ( "elif" expression ":" suite )*\n' |
| 5848 | ' ["else" ":" suite]\n' |
| 5849 | '\n' |
| 5850 | 'It selects exactly one of the suites by evaluating the expressions ' |
| 5851 | 'one\n' |
| 5852 | 'by one until one is found to be true (see section Boolean operations\n' |
| 5853 | 'for the definition of true and false); then that suite is executed\n' |
| 5854 | '(and no other part of the "if" statement is executed or evaluated).\n' |
| 5855 | 'If all expressions are false, the suite of the "else" clause, if\n' |
| 5856 | 'present, is executed.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5857 | 'imaginary': 'Imaginary literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5858 | '******************\n' |
| 5859 | '\n' |
| 5860 | 'Imaginary literals are described by the following lexical ' |
| 5861 | 'definitions:\n' |
| 5862 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5863 | ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5864 | '\n' |
| 5865 | 'An imaginary literal yields a complex number with a real part ' |
| 5866 | 'of 0.0.\n' |
| 5867 | 'Complex numbers are represented as a pair of floating point ' |
| 5868 | 'numbers\n' |
| 5869 | 'and have the same restrictions on their range. To create a ' |
| 5870 | 'complex\n' |
| 5871 | 'number with a nonzero real part, add a floating point number to ' |
| 5872 | 'it,\n' |
| 5873 | 'e.g., "(3+4j)". Some examples of imaginary literals:\n' |
| 5874 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 5875 | ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j ' |
| 5876 | '3.14_15_93j\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 5877 | 'import': 'The "import" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5878 | '**********************\n' |
| 5879 | '\n' |
| 5880 | ' import_stmt ::= "import" module ["as" name] ( "," module ' |
| 5881 | '["as" name] )*\n' |
| 5882 | ' | "from" relative_module "import" identifier ' |
| 5883 | '["as" name]\n' |
| 5884 | ' ( "," identifier ["as" name] )*\n' |
| 5885 | ' | "from" relative_module "import" "(" ' |
| 5886 | 'identifier ["as" name]\n' |
| 5887 | ' ( "," identifier ["as" name] )* [","] ")"\n' |
| 5888 | ' | "from" module "import" "*"\n' |
| 5889 | ' module ::= (identifier ".")* identifier\n' |
| 5890 | ' relative_module ::= "."* module | "."+\n' |
| 5891 | ' name ::= identifier\n' |
| 5892 | '\n' |
| 5893 | 'The basic import statement (no "from" clause) is executed in two\n' |
| 5894 | 'steps:\n' |
| 5895 | '\n' |
| 5896 | '1. find a module, loading and initializing it if necessary\n' |
| 5897 | '\n' |
| 5898 | '2. define a name or names in the local namespace for the scope\n' |
| 5899 | ' where the "import" statement occurs.\n' |
| 5900 | '\n' |
| 5901 | 'When the statement contains multiple clauses (separated by commas) ' |
| 5902 | 'the\n' |
| 5903 | 'two steps are carried out separately for each clause, just as ' |
| 5904 | 'though\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 5905 | 'the clauses had been separated out into individual import ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 5906 | 'statements.\n' |
| 5907 | '\n' |
| 5908 | 'The details of the first step, finding and loading modules are\n' |
| 5909 | 'described in greater detail in the section on the import system, ' |
| 5910 | 'which\n' |
| 5911 | 'also describes the various types of packages and modules that can ' |
| 5912 | 'be\n' |
| 5913 | 'imported, as well as all the hooks that can be used to customize ' |
| 5914 | 'the\n' |
| 5915 | 'import system. Note that failures in this step may indicate ' |
| 5916 | 'either\n' |
| 5917 | 'that the module could not be located, *or* that an error occurred\n' |
| 5918 | 'while initializing the module, which includes execution of the\n' |
| 5919 | "module's code.\n" |
| 5920 | '\n' |
| 5921 | 'If the requested module is retrieved successfully, it will be ' |
| 5922 | 'made\n' |
| 5923 | 'available in the local namespace in one of three ways:\n' |
| 5924 | '\n' |
| 5925 | '* If the module name is followed by "as", then the name following\n' |
| 5926 | ' "as" is bound directly to the imported module.\n' |
| 5927 | '\n' |
| 5928 | '* If no other name is specified, and the module being imported is ' |
| 5929 | 'a\n' |
| 5930 | " top level module, the module's name is bound in the local " |
| 5931 | 'namespace\n' |
| 5932 | ' as a reference to the imported module\n' |
| 5933 | '\n' |
| 5934 | '* If the module being imported is *not* a top level module, then ' |
| 5935 | 'the\n' |
| 5936 | ' name of the top level package that contains the module is bound ' |
| 5937 | 'in\n' |
| 5938 | ' the local namespace as a reference to the top level package. ' |
| 5939 | 'The\n' |
| 5940 | ' imported module must be accessed using its full qualified name\n' |
| 5941 | ' rather than directly\n' |
| 5942 | '\n' |
| 5943 | 'The "from" form uses a slightly more complex process:\n' |
| 5944 | '\n' |
| 5945 | '1. find the module specified in the "from" clause, loading and\n' |
| 5946 | ' initializing it if necessary;\n' |
| 5947 | '\n' |
| 5948 | '2. for each of the identifiers specified in the "import" clauses:\n' |
| 5949 | '\n' |
| 5950 | ' 1. check if the imported module has an attribute by that name\n' |
| 5951 | '\n' |
| 5952 | ' 2. if not, attempt to import a submodule with that name and ' |
| 5953 | 'then\n' |
| 5954 | ' check the imported module again for that attribute\n' |
| 5955 | '\n' |
| 5956 | ' 3. if the attribute is not found, "ImportError" is raised.\n' |
| 5957 | '\n' |
| 5958 | ' 4. otherwise, a reference to that value is stored in the local\n' |
| 5959 | ' namespace, using the name in the "as" clause if it is ' |
| 5960 | 'present,\n' |
| 5961 | ' otherwise using the attribute name\n' |
| 5962 | '\n' |
| 5963 | 'Examples:\n' |
| 5964 | '\n' |
| 5965 | ' import foo # foo imported and bound locally\n' |
| 5966 | ' import foo.bar.baz # foo.bar.baz imported, foo bound ' |
| 5967 | 'locally\n' |
| 5968 | ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as ' |
| 5969 | 'fbb\n' |
| 5970 | ' from foo.bar import baz # foo.bar.baz imported and bound as ' |
| 5971 | 'baz\n' |
| 5972 | ' from foo import attr # foo imported and foo.attr bound as ' |
| 5973 | 'attr\n' |
| 5974 | '\n' |
| 5975 | 'If the list of identifiers is replaced by a star ("\'*\'"), all ' |
| 5976 | 'public\n' |
| 5977 | 'names defined in the module are bound in the local namespace for ' |
| 5978 | 'the\n' |
| 5979 | 'scope where the "import" statement occurs.\n' |
| 5980 | '\n' |
| 5981 | 'The *public names* defined by a module are determined by checking ' |
| 5982 | 'the\n' |
| 5983 | 'module\'s namespace for a variable named "__all__"; if defined, it ' |
| 5984 | 'must\n' |
| 5985 | 'be a sequence of strings which are names defined or imported by ' |
| 5986 | 'that\n' |
| 5987 | 'module. The names given in "__all__" are all considered public ' |
| 5988 | 'and\n' |
| 5989 | 'are required to exist. If "__all__" is not defined, the set of ' |
| 5990 | 'public\n' |
| 5991 | "names includes all names found in the module's namespace which do " |
| 5992 | 'not\n' |
| 5993 | 'begin with an underscore character ("\'_\'"). "__all__" should ' |
| 5994 | 'contain\n' |
| 5995 | 'the entire public API. It is intended to avoid accidentally ' |
| 5996 | 'exporting\n' |
| 5997 | 'items that are not part of the API (such as library modules which ' |
| 5998 | 'were\n' |
| 5999 | 'imported and used within the module).\n' |
| 6000 | '\n' |
| 6001 | 'The wild card form of import --- "from module import *" --- is ' |
| 6002 | 'only\n' |
| 6003 | 'allowed at the module level. Attempting to use it in class or\n' |
| 6004 | 'function definitions will raise a "SyntaxError".\n' |
| 6005 | '\n' |
| 6006 | 'When specifying what module to import you do not have to specify ' |
| 6007 | 'the\n' |
| 6008 | 'absolute name of the module. When a module or package is ' |
| 6009 | 'contained\n' |
| 6010 | 'within another package it is possible to make a relative import ' |
| 6011 | 'within\n' |
| 6012 | 'the same top package without having to mention the package name. ' |
| 6013 | 'By\n' |
| 6014 | 'using leading dots in the specified module or package after "from" ' |
| 6015 | 'you\n' |
| 6016 | 'can specify how high to traverse up the current package hierarchy\n' |
| 6017 | 'without specifying exact names. One leading dot means the current\n' |
| 6018 | 'package where the module making the import exists. Two dots means ' |
| 6019 | 'up\n' |
| 6020 | 'one package level. Three dots is up two levels, etc. So if you ' |
| 6021 | 'execute\n' |
| 6022 | '"from . import mod" from a module in the "pkg" package then you ' |
| 6023 | 'will\n' |
| 6024 | 'end up importing "pkg.mod". If you execute "from ..subpkg2 import ' |
| 6025 | 'mod"\n' |
| 6026 | 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n' |
| 6027 | 'specification for relative imports is contained within **PEP ' |
| 6028 | '328**.\n' |
| 6029 | '\n' |
| 6030 | '"importlib.import_module()" is provided to support applications ' |
| 6031 | 'that\n' |
| 6032 | 'determine dynamically the modules to be loaded.\n' |
| 6033 | '\n' |
| 6034 | '\n' |
| 6035 | 'Future statements\n' |
| 6036 | '=================\n' |
| 6037 | '\n' |
| 6038 | 'A *future statement* is a directive to the compiler that a ' |
| 6039 | 'particular\n' |
| 6040 | 'module should be compiled using syntax or semantics that will be\n' |
| 6041 | 'available in a specified future release of Python where the ' |
| 6042 | 'feature\n' |
| 6043 | 'becomes standard.\n' |
| 6044 | '\n' |
| 6045 | 'The future statement is intended to ease migration to future ' |
| 6046 | 'versions\n' |
| 6047 | 'of Python that introduce incompatible changes to the language. ' |
| 6048 | 'It\n' |
| 6049 | 'allows use of the new features on a per-module basis before the\n' |
| 6050 | 'release in which the feature becomes standard.\n' |
| 6051 | '\n' |
| 6052 | ' future_statement ::= "from" "__future__" "import" feature ["as" ' |
| 6053 | 'name]\n' |
| 6054 | ' ("," feature ["as" name])*\n' |
| 6055 | ' | "from" "__future__" "import" "(" feature ' |
| 6056 | '["as" name]\n' |
| 6057 | ' ("," feature ["as" name])* [","] ")"\n' |
| 6058 | ' feature ::= identifier\n' |
| 6059 | ' name ::= identifier\n' |
| 6060 | '\n' |
| 6061 | 'A future statement must appear near the top of the module. The ' |
| 6062 | 'only\n' |
| 6063 | 'lines that can appear before a future statement are:\n' |
| 6064 | '\n' |
| 6065 | '* the module docstring (if any),\n' |
| 6066 | '\n' |
| 6067 | '* comments,\n' |
| 6068 | '\n' |
| 6069 | '* blank lines, and\n' |
| 6070 | '\n' |
| 6071 | '* other future statements.\n' |
| 6072 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 6073 | 'The only feature in Python 3.7 that requires using the future\n' |
| 6074 | 'statement is "annotations".\n' |
| 6075 | '\n' |
| 6076 | 'All historical features enabled by the future statement are still\n' |
| 6077 | 'recognized by Python 3. The list includes "absolute_import",\n' |
| 6078 | '"division", "generators", "generator_stop", "unicode_literals",\n' |
| 6079 | '"print_function", "nested_scopes" and "with_statement". They are ' |
| 6080 | 'all\n' |
| 6081 | 'redundant because they are always enabled, and only kept for ' |
| 6082 | 'backwards\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6083 | 'compatibility.\n' |
| 6084 | '\n' |
| 6085 | 'A future statement is recognized and treated specially at compile\n' |
| 6086 | 'time: Changes to the semantics of core constructs are often\n' |
| 6087 | 'implemented by generating different code. It may even be the ' |
| 6088 | 'case\n' |
| 6089 | 'that a new feature introduces new incompatible syntax (such as a ' |
| 6090 | 'new\n' |
| 6091 | 'reserved word), in which case the compiler may need to parse the\n' |
| 6092 | 'module differently. Such decisions cannot be pushed off until\n' |
| 6093 | 'runtime.\n' |
| 6094 | '\n' |
| 6095 | 'For any given release, the compiler knows which feature names ' |
| 6096 | 'have\n' |
| 6097 | 'been defined, and raises a compile-time error if a future ' |
| 6098 | 'statement\n' |
| 6099 | 'contains a feature not known to it.\n' |
| 6100 | '\n' |
| 6101 | 'The direct runtime semantics are the same as for any import ' |
| 6102 | 'statement:\n' |
| 6103 | 'there is a standard module "__future__", described later, and it ' |
| 6104 | 'will\n' |
| 6105 | 'be imported in the usual way at the time the future statement is\n' |
| 6106 | 'executed.\n' |
| 6107 | '\n' |
| 6108 | 'The interesting runtime semantics depend on the specific feature\n' |
| 6109 | 'enabled by the future statement.\n' |
| 6110 | '\n' |
| 6111 | 'Note that there is nothing special about the statement:\n' |
| 6112 | '\n' |
| 6113 | ' import __future__ [as name]\n' |
| 6114 | '\n' |
| 6115 | "That is not a future statement; it's an ordinary import statement " |
| 6116 | 'with\n' |
| 6117 | 'no special semantics or syntax restrictions.\n' |
| 6118 | '\n' |
| 6119 | 'Code compiled by calls to the built-in functions "exec()" and\n' |
| 6120 | '"compile()" that occur in a module "M" containing a future ' |
| 6121 | 'statement\n' |
| 6122 | 'will, by default, use the new syntax or semantics associated with ' |
| 6123 | 'the\n' |
| 6124 | 'future statement. This can be controlled by optional arguments ' |
| 6125 | 'to\n' |
| 6126 | '"compile()" --- see the documentation of that function for ' |
| 6127 | 'details.\n' |
| 6128 | '\n' |
| 6129 | 'A future statement typed at an interactive interpreter prompt ' |
| 6130 | 'will\n' |
| 6131 | 'take effect for the rest of the interpreter session. If an\n' |
| 6132 | 'interpreter is started with the "-i" option, is passed a script ' |
| 6133 | 'name\n' |
| 6134 | 'to execute, and the script includes a future statement, it will be ' |
| 6135 | 'in\n' |
| 6136 | 'effect in the interactive session started after the script is\n' |
| 6137 | 'executed.\n' |
| 6138 | '\n' |
| 6139 | 'See also:\n' |
| 6140 | '\n' |
| 6141 | ' **PEP 236** - Back to the __future__\n' |
| 6142 | ' The original proposal for the __future__ mechanism.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6143 | 'in': 'Membership test operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6144 | '**************************\n' |
| 6145 | '\n' |
| 6146 | '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] | 6147 | 'evaluates to "True" if *x* is a member of *s*, and "False" otherwise.\n' |
| 6148 | '"x not in s" returns the negation of "x in s". All built-in ' |
| 6149 | 'sequences\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6150 | 'and set types support this as well as dictionary, for which "in" ' |
| 6151 | 'tests\n' |
| 6152 | 'whether the dictionary has a given key. For container types such as\n' |
| 6153 | 'list, tuple, set, frozenset, dict, or collections.deque, the\n' |
| 6154 | 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n' |
| 6155 | 'y)".\n' |
| 6156 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6157 | 'For the string and bytes types, "x in y" is "True" if and only if *x*\n' |
| 6158 | 'is a substring of *y*. An equivalent test is "y.find(x) != -1".\n' |
| 6159 | 'Empty strings are always considered to be a substring of any other\n' |
| 6160 | 'string, so """ in "abc"" will return "True".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6161 | '\n' |
| 6162 | 'For user-defined classes which define the "__contains__()" method, "x\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6163 | 'in y" returns "True" if "y.__contains__(x)" returns a true value, and\n' |
| 6164 | '"False" otherwise.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6165 | '\n' |
| 6166 | 'For user-defined classes which do not define "__contains__()" but do\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6167 | 'define "__iter__()", "x in y" is "True" if some value "z" with "x ==\n' |
| 6168 | '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] | 6169 | 'during the iteration, it is as if "in" raised that exception.\n' |
| 6170 | '\n' |
| 6171 | '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] | 6172 | '"__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] | 6173 | 'negative integer index *i* such that "x == y[i]", and all lower\n' |
| 6174 | 'integer indices do not raise "IndexError" exception. (If any other\n' |
| 6175 | 'exception is raised, it is as if "in" raised that exception).\n' |
| 6176 | '\n' |
| 6177 | 'The operator "not in" is defined to have the inverse true value of\n' |
| 6178 | '"in".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6179 | 'integers': 'Integer literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6180 | '****************\n' |
| 6181 | '\n' |
| 6182 | 'Integer literals are described by the following lexical ' |
| 6183 | 'definitions:\n' |
| 6184 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6185 | ' integer ::= decinteger | bininteger | octinteger | ' |
| 6186 | 'hexinteger\n' |
| 6187 | ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] ' |
| 6188 | '"0")*\n' |
| 6189 | ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n' |
| 6190 | ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n' |
| 6191 | ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n' |
| 6192 | ' nonzerodigit ::= "1"..."9"\n' |
| 6193 | ' digit ::= "0"..."9"\n' |
| 6194 | ' bindigit ::= "0" | "1"\n' |
| 6195 | ' octdigit ::= "0"..."7"\n' |
| 6196 | ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6197 | '\n' |
| 6198 | 'There is no limit for the length of integer literals apart from ' |
| 6199 | 'what\n' |
| 6200 | 'can be stored in available memory.\n' |
| 6201 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6202 | 'Underscores are ignored for determining the numeric value of ' |
| 6203 | 'the\n' |
| 6204 | 'literal. They can be used to group digits for enhanced ' |
| 6205 | 'readability.\n' |
| 6206 | 'One underscore can occur between digits, and after base ' |
| 6207 | 'specifiers\n' |
| 6208 | 'like "0x".\n' |
| 6209 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6210 | 'Note that leading zeros in a non-zero decimal number are not ' |
| 6211 | 'allowed.\n' |
| 6212 | 'This is for disambiguation with C-style octal literals, which ' |
| 6213 | 'Python\n' |
| 6214 | 'used before version 3.0.\n' |
| 6215 | '\n' |
| 6216 | 'Some examples of integer literals:\n' |
| 6217 | '\n' |
| 6218 | ' 7 2147483647 0o177 0b100110111\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6219 | ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n' |
| 6220 | ' 100_000_000_000 0b_1110_0101\n' |
| 6221 | '\n' |
| 6222 | 'Changed in version 3.6: Underscores are now allowed for ' |
| 6223 | 'grouping\n' |
| 6224 | 'purposes in literals.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6225 | 'lambda': 'Lambdas\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6226 | '*******\n' |
| 6227 | '\n' |
| 6228 | ' lambda_expr ::= "lambda" [parameter_list]: expression\n' |
| 6229 | ' lambda_expr_nocond ::= "lambda" [parameter_list]: ' |
| 6230 | 'expression_nocond\n' |
| 6231 | '\n' |
| 6232 | 'Lambda expressions (sometimes called lambda forms) are used to ' |
| 6233 | 'create\n' |
| 6234 | 'anonymous functions. The expression "lambda arguments: ' |
| 6235 | 'expression"\n' |
| 6236 | 'yields a function object. The unnamed object behaves like a ' |
| 6237 | 'function\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 6238 | 'object defined with:\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6239 | '\n' |
| 6240 | ' def <lambda>(arguments):\n' |
| 6241 | ' return expression\n' |
| 6242 | '\n' |
| 6243 | 'See section Function definitions for the syntax of parameter ' |
| 6244 | 'lists.\n' |
| 6245 | 'Note that functions created with lambda expressions cannot ' |
| 6246 | 'contain\n' |
| 6247 | 'statements or annotations.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6248 | 'lists': 'List displays\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6249 | '*************\n' |
| 6250 | '\n' |
| 6251 | 'A list display is a possibly empty series of expressions enclosed ' |
| 6252 | 'in\n' |
| 6253 | 'square brackets:\n' |
| 6254 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 6255 | ' list_display ::= "[" [starred_list | comprehension] "]"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6256 | '\n' |
| 6257 | 'A list display yields a new list object, the contents being ' |
| 6258 | 'specified\n' |
| 6259 | 'by either a list of expressions or a comprehension. When a comma-\n' |
| 6260 | 'separated list of expressions is supplied, its elements are ' |
| 6261 | 'evaluated\n' |
| 6262 | 'from left to right and placed into the list object in that order.\n' |
| 6263 | 'When a comprehension is supplied, the list is constructed from the\n' |
| 6264 | 'elements resulting from the comprehension.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6265 | 'naming': 'Naming and binding\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6266 | '******************\n' |
| 6267 | '\n' |
| 6268 | '\n' |
| 6269 | 'Binding of names\n' |
| 6270 | '================\n' |
| 6271 | '\n' |
| 6272 | '*Names* refer to objects. Names are introduced by name binding\n' |
| 6273 | 'operations.\n' |
| 6274 | '\n' |
| 6275 | 'The following constructs bind names: formal parameters to ' |
| 6276 | 'functions,\n' |
| 6277 | '"import" statements, class and function definitions (these bind ' |
| 6278 | 'the\n' |
| 6279 | 'class or function name in the defining block), and targets that ' |
| 6280 | 'are\n' |
| 6281 | 'identifiers if occurring in an assignment, "for" loop header, or ' |
| 6282 | 'after\n' |
| 6283 | '"as" in a "with" statement or "except" clause. The "import" ' |
| 6284 | 'statement\n' |
| 6285 | 'of the form "from ... import *" binds all names defined in the\n' |
| 6286 | 'imported module, except those beginning with an underscore. This ' |
| 6287 | 'form\n' |
| 6288 | 'may only be used at the module level.\n' |
| 6289 | '\n' |
| 6290 | 'A target occurring in a "del" statement is also considered bound ' |
| 6291 | 'for\n' |
| 6292 | 'this purpose (though the actual semantics are to unbind the ' |
| 6293 | 'name).\n' |
| 6294 | '\n' |
| 6295 | 'Each assignment or import statement occurs within a block defined ' |
| 6296 | 'by a\n' |
| 6297 | 'class or function definition or at the module level (the ' |
| 6298 | 'top-level\n' |
| 6299 | 'code block).\n' |
| 6300 | '\n' |
| 6301 | 'If a name is bound in a block, it is a local variable of that ' |
| 6302 | 'block,\n' |
| 6303 | 'unless declared as "nonlocal" or "global". If a name is bound at ' |
| 6304 | 'the\n' |
| 6305 | 'module level, it is a global variable. (The variables of the ' |
| 6306 | 'module\n' |
| 6307 | 'code block are local and global.) If a variable is used in a ' |
| 6308 | 'code\n' |
| 6309 | 'block but not defined there, it is a *free variable*.\n' |
| 6310 | '\n' |
| 6311 | 'Each occurrence of a name in the program text refers to the ' |
| 6312 | '*binding*\n' |
| 6313 | 'of that name established by the following name resolution rules.\n' |
| 6314 | '\n' |
| 6315 | '\n' |
| 6316 | 'Resolution of names\n' |
| 6317 | '===================\n' |
| 6318 | '\n' |
| 6319 | 'A *scope* defines the visibility of a name within a block. If a ' |
| 6320 | 'local\n' |
| 6321 | 'variable is defined in a block, its scope includes that block. If ' |
| 6322 | 'the\n' |
| 6323 | 'definition occurs in a function block, the scope extends to any ' |
| 6324 | 'blocks\n' |
| 6325 | 'contained within the defining one, unless a contained block ' |
| 6326 | 'introduces\n' |
| 6327 | 'a different binding for the name.\n' |
| 6328 | '\n' |
| 6329 | 'When a name is used in a code block, it is resolved using the ' |
| 6330 | 'nearest\n' |
| 6331 | 'enclosing scope. The set of all such scopes visible to a code ' |
| 6332 | 'block\n' |
| 6333 | "is called the block's *environment*.\n" |
| 6334 | '\n' |
| 6335 | 'When a name is not found at all, a "NameError" exception is ' |
| 6336 | 'raised. If\n' |
| 6337 | 'the current scope is a function scope, and the name refers to a ' |
| 6338 | 'local\n' |
| 6339 | 'variable that has not yet been bound to a value at the point where ' |
| 6340 | 'the\n' |
| 6341 | 'name is used, an "UnboundLocalError" exception is raised.\n' |
| 6342 | '"UnboundLocalError" is a subclass of "NameError".\n' |
| 6343 | '\n' |
| 6344 | 'If a name binding operation occurs anywhere within a code block, ' |
| 6345 | 'all\n' |
| 6346 | 'uses of the name within the block are treated as references to ' |
| 6347 | 'the\n' |
| 6348 | 'current block. This can lead to errors when a name is used within ' |
| 6349 | 'a\n' |
| 6350 | 'block before it is bound. This rule is subtle. Python lacks\n' |
| 6351 | 'declarations and allows name binding operations to occur anywhere\n' |
| 6352 | 'within a code block. The local variables of a code block can be\n' |
| 6353 | 'determined by scanning the entire text of the block for name ' |
| 6354 | 'binding\n' |
| 6355 | 'operations.\n' |
| 6356 | '\n' |
| 6357 | 'If the "global" statement occurs within a block, all uses of the ' |
| 6358 | 'name\n' |
| 6359 | 'specified in the statement refer to the binding of that name in ' |
| 6360 | 'the\n' |
| 6361 | 'top-level namespace. Names are resolved in the top-level ' |
| 6362 | 'namespace by\n' |
| 6363 | 'searching the global namespace, i.e. the namespace of the module\n' |
| 6364 | 'containing the code block, and the builtins namespace, the ' |
| 6365 | 'namespace\n' |
| 6366 | 'of the module "builtins". The global namespace is searched ' |
| 6367 | 'first. If\n' |
| 6368 | 'the name is not found there, the builtins namespace is searched. ' |
| 6369 | 'The\n' |
| 6370 | '"global" statement must precede all uses of the name.\n' |
| 6371 | '\n' |
| 6372 | 'The "global" statement has the same scope as a name binding ' |
| 6373 | 'operation\n' |
| 6374 | 'in the same block. If the nearest enclosing scope for a free ' |
| 6375 | 'variable\n' |
| 6376 | 'contains a global statement, the free variable is treated as a ' |
| 6377 | 'global.\n' |
| 6378 | '\n' |
| 6379 | 'The "nonlocal" statement causes corresponding names to refer to\n' |
| 6380 | 'previously bound variables in the nearest enclosing function ' |
| 6381 | 'scope.\n' |
| 6382 | '"SyntaxError" is raised at compile time if the given name does ' |
| 6383 | 'not\n' |
| 6384 | 'exist in any enclosing function scope.\n' |
| 6385 | '\n' |
| 6386 | 'The namespace for a module is automatically created the first time ' |
| 6387 | 'a\n' |
| 6388 | 'module is imported. The main module for a script is always ' |
| 6389 | 'called\n' |
| 6390 | '"__main__".\n' |
| 6391 | '\n' |
| 6392 | 'Class definition blocks and arguments to "exec()" and "eval()" ' |
| 6393 | 'are\n' |
| 6394 | 'special in the context of name resolution. A class definition is ' |
| 6395 | 'an\n' |
| 6396 | 'executable statement that may use and define names. These ' |
| 6397 | 'references\n' |
| 6398 | 'follow the normal rules for name resolution with an exception ' |
| 6399 | 'that\n' |
| 6400 | 'unbound local variables are looked up in the global namespace. ' |
| 6401 | 'The\n' |
| 6402 | 'namespace of the class definition becomes the attribute dictionary ' |
| 6403 | 'of\n' |
| 6404 | 'the class. The scope of names defined in a class block is limited ' |
| 6405 | 'to\n' |
| 6406 | 'the class block; it does not extend to the code blocks of methods ' |
| 6407 | '--\n' |
| 6408 | 'this includes comprehensions and generator expressions since they ' |
| 6409 | 'are\n' |
| 6410 | 'implemented using a function scope. This means that the ' |
| 6411 | 'following\n' |
| 6412 | 'will fail:\n' |
| 6413 | '\n' |
| 6414 | ' class A:\n' |
| 6415 | ' a = 42\n' |
| 6416 | ' b = list(a + i for i in range(10))\n' |
| 6417 | '\n' |
| 6418 | '\n' |
| 6419 | 'Builtins and restricted execution\n' |
| 6420 | '=================================\n' |
| 6421 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6422 | '**CPython implementation detail:** Users should not touch\n' |
| 6423 | '"__builtins__"; it is strictly an implementation detail. Users\n' |
| 6424 | 'wanting to override values in the builtins namespace should ' |
| 6425 | '"import"\n' |
| 6426 | 'the "builtins" module and modify its attributes appropriately.\n' |
| 6427 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6428 | 'The builtins namespace associated with the execution of a code ' |
| 6429 | 'block\n' |
| 6430 | 'is actually found by looking up the name "__builtins__" in its ' |
| 6431 | 'global\n' |
| 6432 | 'namespace; this should be a dictionary or a module (in the latter ' |
| 6433 | 'case\n' |
| 6434 | "the module's dictionary is used). By default, when in the " |
| 6435 | '"__main__"\n' |
| 6436 | 'module, "__builtins__" is the built-in module "builtins"; when in ' |
| 6437 | 'any\n' |
| 6438 | 'other module, "__builtins__" is an alias for the dictionary of ' |
| 6439 | 'the\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6440 | '"builtins" module itself.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6441 | '\n' |
| 6442 | '\n' |
| 6443 | 'Interaction with dynamic features\n' |
| 6444 | '=================================\n' |
| 6445 | '\n' |
| 6446 | 'Name resolution of free variables occurs at runtime, not at ' |
| 6447 | 'compile\n' |
| 6448 | 'time. This means that the following code will print 42:\n' |
| 6449 | '\n' |
| 6450 | ' i = 10\n' |
| 6451 | ' def f():\n' |
| 6452 | ' print(i)\n' |
| 6453 | ' i = 42\n' |
| 6454 | ' f()\n' |
| 6455 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6456 | 'The "eval()" and "exec()" functions do not have access to the ' |
| 6457 | 'full\n' |
| 6458 | 'environment for resolving names. Names may be resolved in the ' |
| 6459 | 'local\n' |
| 6460 | 'and global namespaces of the caller. Free variables are not ' |
| 6461 | 'resolved\n' |
| 6462 | 'in the nearest enclosing namespace, but in the global namespace. ' |
| 6463 | '[1]\n' |
| 6464 | 'The "exec()" and "eval()" functions have optional arguments to\n' |
| 6465 | 'override the global and local namespace. If only one namespace ' |
| 6466 | 'is\n' |
| 6467 | 'specified, it is used for both.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6468 | 'nonlocal': 'The "nonlocal" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6469 | '************************\n' |
| 6470 | '\n' |
| 6471 | ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' |
| 6472 | '\n' |
| 6473 | 'The "nonlocal" statement causes the listed identifiers to refer ' |
| 6474 | 'to\n' |
| 6475 | 'previously bound variables in the nearest enclosing scope ' |
| 6476 | 'excluding\n' |
| 6477 | 'globals. This is important because the default behavior for ' |
| 6478 | 'binding is\n' |
| 6479 | 'to search the local namespace first. The statement allows\n' |
| 6480 | 'encapsulated code to rebind variables outside of the local ' |
| 6481 | 'scope\n' |
| 6482 | 'besides the global (module) scope.\n' |
| 6483 | '\n' |
| 6484 | 'Names listed in a "nonlocal" statement, unlike those listed in ' |
| 6485 | 'a\n' |
| 6486 | '"global" statement, must refer to pre-existing bindings in an\n' |
| 6487 | 'enclosing scope (the scope in which a new binding should be ' |
| 6488 | 'created\n' |
| 6489 | 'cannot be determined unambiguously).\n' |
| 6490 | '\n' |
| 6491 | 'Names listed in a "nonlocal" statement must not collide with ' |
| 6492 | 'pre-\n' |
| 6493 | 'existing bindings in the local scope.\n' |
| 6494 | '\n' |
| 6495 | 'See also:\n' |
| 6496 | '\n' |
| 6497 | ' **PEP 3104** - Access to Names in Outer Scopes\n' |
| 6498 | ' The specification for the "nonlocal" statement.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6499 | 'numbers': 'Numeric literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6500 | '****************\n' |
| 6501 | '\n' |
| 6502 | 'There are three types of numeric literals: integers, floating ' |
| 6503 | 'point\n' |
| 6504 | 'numbers, and imaginary numbers. There are no complex literals\n' |
| 6505 | '(complex numbers can be formed by adding a real number and an\n' |
| 6506 | 'imaginary number).\n' |
| 6507 | '\n' |
| 6508 | 'Note that numeric literals do not include a sign; a phrase like ' |
| 6509 | '"-1"\n' |
| 6510 | 'is actually an expression composed of the unary operator \'"-"\' ' |
| 6511 | 'and the\n' |
| 6512 | 'literal "1".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6513 | 'numeric-types': 'Emulating numeric types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6514 | '***********************\n' |
| 6515 | '\n' |
| 6516 | 'The following methods can be defined to emulate numeric ' |
| 6517 | 'objects.\n' |
| 6518 | 'Methods corresponding to operations that are not supported ' |
| 6519 | 'by the\n' |
| 6520 | 'particular kind of number implemented (e.g., bitwise ' |
| 6521 | 'operations for\n' |
| 6522 | 'non-integral numbers) should be left undefined.\n' |
| 6523 | '\n' |
| 6524 | 'object.__add__(self, other)\n' |
| 6525 | 'object.__sub__(self, other)\n' |
| 6526 | 'object.__mul__(self, other)\n' |
| 6527 | 'object.__matmul__(self, other)\n' |
| 6528 | 'object.__truediv__(self, other)\n' |
| 6529 | 'object.__floordiv__(self, other)\n' |
| 6530 | 'object.__mod__(self, other)\n' |
| 6531 | 'object.__divmod__(self, other)\n' |
| 6532 | 'object.__pow__(self, other[, modulo])\n' |
| 6533 | 'object.__lshift__(self, other)\n' |
| 6534 | 'object.__rshift__(self, other)\n' |
| 6535 | 'object.__and__(self, other)\n' |
| 6536 | 'object.__xor__(self, other)\n' |
| 6537 | 'object.__or__(self, other)\n' |
| 6538 | '\n' |
| 6539 | ' These methods are called to implement the binary ' |
| 6540 | 'arithmetic\n' |
| 6541 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 6542 | '"divmod()",\n' |
| 6543 | ' "pow()", "**", "<<", ">>", "&", "^", "|"). For ' |
| 6544 | 'instance, to\n' |
| 6545 | ' evaluate the expression "x + y", where *x* is an ' |
| 6546 | 'instance of a\n' |
| 6547 | ' class that has an "__add__()" method, "x.__add__(y)" is ' |
| 6548 | 'called.\n' |
| 6549 | ' The "__divmod__()" method should be the equivalent to ' |
| 6550 | 'using\n' |
| 6551 | ' "__floordiv__()" and "__mod__()"; it should not be ' |
| 6552 | 'related to\n' |
| 6553 | ' "__truediv__()". Note that "__pow__()" should be ' |
| 6554 | 'defined to accept\n' |
| 6555 | ' an optional third argument if the ternary version of the ' |
| 6556 | 'built-in\n' |
| 6557 | ' "pow()" function is to be supported.\n' |
| 6558 | '\n' |
| 6559 | ' If one of those methods does not support the operation ' |
| 6560 | 'with the\n' |
| 6561 | ' supplied arguments, it should return "NotImplemented".\n' |
| 6562 | '\n' |
| 6563 | 'object.__radd__(self, other)\n' |
| 6564 | 'object.__rsub__(self, other)\n' |
| 6565 | 'object.__rmul__(self, other)\n' |
| 6566 | 'object.__rmatmul__(self, other)\n' |
| 6567 | 'object.__rtruediv__(self, other)\n' |
| 6568 | 'object.__rfloordiv__(self, other)\n' |
| 6569 | 'object.__rmod__(self, other)\n' |
| 6570 | 'object.__rdivmod__(self, other)\n' |
| 6571 | 'object.__rpow__(self, other)\n' |
| 6572 | 'object.__rlshift__(self, other)\n' |
| 6573 | 'object.__rrshift__(self, other)\n' |
| 6574 | 'object.__rand__(self, other)\n' |
| 6575 | 'object.__rxor__(self, other)\n' |
| 6576 | 'object.__ror__(self, other)\n' |
| 6577 | '\n' |
| 6578 | ' These methods are called to implement the binary ' |
| 6579 | 'arithmetic\n' |
| 6580 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 6581 | '"divmod()",\n' |
| 6582 | ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' |
| 6583 | '(swapped)\n' |
| 6584 | ' operands. These functions are only called if the left ' |
| 6585 | 'operand does\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 6586 | ' not support the corresponding operation [3] and the ' |
| 6587 | 'operands are of\n' |
| 6588 | ' different types. [4] For instance, to evaluate the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6589 | 'expression "x -\n' |
| 6590 | ' y", where *y* is an instance of a class that has an ' |
| 6591 | '"__rsub__()"\n' |
| 6592 | ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' |
| 6593 | 'returns\n' |
| 6594 | ' *NotImplemented*.\n' |
| 6595 | '\n' |
| 6596 | ' Note that ternary "pow()" will not try calling ' |
| 6597 | '"__rpow__()" (the\n' |
| 6598 | ' coercion rules would become too complicated).\n' |
| 6599 | '\n' |
| 6600 | " Note: If the right operand's type is a subclass of the " |
| 6601 | 'left\n' |
| 6602 | " operand's type and that subclass provides the " |
| 6603 | 'reflected method\n' |
| 6604 | ' for the operation, this method will be called before ' |
| 6605 | 'the left\n' |
| 6606 | " operand's non-reflected method. This behavior allows " |
| 6607 | 'subclasses\n' |
| 6608 | " to override their ancestors' operations.\n" |
| 6609 | '\n' |
| 6610 | 'object.__iadd__(self, other)\n' |
| 6611 | 'object.__isub__(self, other)\n' |
| 6612 | 'object.__imul__(self, other)\n' |
| 6613 | 'object.__imatmul__(self, other)\n' |
| 6614 | 'object.__itruediv__(self, other)\n' |
| 6615 | 'object.__ifloordiv__(self, other)\n' |
| 6616 | 'object.__imod__(self, other)\n' |
| 6617 | 'object.__ipow__(self, other[, modulo])\n' |
| 6618 | 'object.__ilshift__(self, other)\n' |
| 6619 | 'object.__irshift__(self, other)\n' |
| 6620 | 'object.__iand__(self, other)\n' |
| 6621 | 'object.__ixor__(self, other)\n' |
| 6622 | 'object.__ior__(self, other)\n' |
| 6623 | '\n' |
| 6624 | ' These methods are called to implement the augmented ' |
| 6625 | 'arithmetic\n' |
| 6626 | ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' |
| 6627 | '"**=",\n' |
| 6628 | ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' |
| 6629 | 'attempt to\n' |
| 6630 | ' do the operation in-place (modifying *self*) and return ' |
| 6631 | 'the result\n' |
| 6632 | ' (which could be, but does not have to be, *self*). If a ' |
| 6633 | 'specific\n' |
| 6634 | ' method is not defined, the augmented assignment falls ' |
| 6635 | 'back to the\n' |
| 6636 | ' normal methods. For instance, if *x* is an instance of ' |
| 6637 | 'a class\n' |
| 6638 | ' with an "__iadd__()" method, "x += y" is equivalent to ' |
| 6639 | '"x =\n' |
| 6640 | ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' |
| 6641 | '"y.__radd__(x)" are\n' |
| 6642 | ' considered, as with the evaluation of "x + y". In ' |
| 6643 | 'certain\n' |
| 6644 | ' situations, augmented assignment can result in ' |
| 6645 | 'unexpected errors\n' |
| 6646 | " (see Why does a_tuple[i] += ['item'] raise an exception " |
| 6647 | 'when the\n' |
| 6648 | ' addition works?), but this behavior is in fact part of ' |
| 6649 | 'the data\n' |
| 6650 | ' model.\n' |
| 6651 | '\n' |
| 6652 | 'object.__neg__(self)\n' |
| 6653 | 'object.__pos__(self)\n' |
| 6654 | 'object.__abs__(self)\n' |
| 6655 | 'object.__invert__(self)\n' |
| 6656 | '\n' |
| 6657 | ' Called to implement the unary arithmetic operations ' |
| 6658 | '("-", "+",\n' |
| 6659 | ' "abs()" and "~").\n' |
| 6660 | '\n' |
| 6661 | 'object.__complex__(self)\n' |
| 6662 | 'object.__int__(self)\n' |
| 6663 | 'object.__float__(self)\n' |
| 6664 | 'object.__round__(self[, n])\n' |
| 6665 | '\n' |
| 6666 | ' Called to implement the built-in functions "complex()", ' |
| 6667 | '"int()",\n' |
| 6668 | ' "float()" and "round()". Should return a value of the ' |
| 6669 | 'appropriate\n' |
| 6670 | ' type.\n' |
| 6671 | '\n' |
| 6672 | 'object.__index__(self)\n' |
| 6673 | '\n' |
| 6674 | ' Called to implement "operator.index()", and whenever ' |
| 6675 | 'Python needs\n' |
| 6676 | ' to losslessly convert the numeric object to an integer ' |
| 6677 | 'object (such\n' |
| 6678 | ' as in slicing, or in the built-in "bin()", "hex()" and ' |
| 6679 | '"oct()"\n' |
| 6680 | ' functions). Presence of this method indicates that the ' |
| 6681 | 'numeric\n' |
| 6682 | ' object is an integer type. Must return an integer.\n' |
| 6683 | '\n' |
| 6684 | ' Note: In order to have a coherent integer type class, ' |
| 6685 | 'when\n' |
| 6686 | ' "__index__()" is defined "__int__()" should also be ' |
| 6687 | 'defined, and\n' |
| 6688 | ' both should return the same value.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6689 | 'objects': 'Objects, values and types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6690 | '*************************\n' |
| 6691 | '\n' |
| 6692 | "*Objects* are Python's abstraction for data. All data in a " |
| 6693 | 'Python\n' |
| 6694 | 'program is represented by objects or by relations between ' |
| 6695 | 'objects. (In\n' |
| 6696 | 'a sense, and in conformance to Von Neumann\'s model of a "stored\n' |
| 6697 | 'program computer," code is also represented by objects.)\n' |
| 6698 | '\n' |
| 6699 | "Every object has an identity, a type and a value. An object's\n" |
| 6700 | '*identity* never changes once it has been created; you may think ' |
| 6701 | 'of it\n' |
| 6702 | 'as the object\'s address in memory. The \'"is"\' operator ' |
| 6703 | 'compares the\n' |
| 6704 | 'identity of two objects; the "id()" function returns an integer\n' |
| 6705 | 'representing its identity.\n' |
| 6706 | '\n' |
| 6707 | '**CPython implementation detail:** For CPython, "id(x)" is the ' |
| 6708 | 'memory\n' |
| 6709 | 'address where "x" is stored.\n' |
| 6710 | '\n' |
| 6711 | "An object's type determines the operations that the object " |
| 6712 | 'supports\n' |
| 6713 | '(e.g., "does it have a length?") and also defines the possible ' |
| 6714 | 'values\n' |
| 6715 | 'for objects of that type. The "type()" function returns an ' |
| 6716 | "object's\n" |
| 6717 | 'type (which is an object itself). Like its identity, an ' |
| 6718 | "object's\n" |
| 6719 | '*type* is also unchangeable. [1]\n' |
| 6720 | '\n' |
| 6721 | 'The *value* of some objects can change. Objects whose value can\n' |
| 6722 | 'change are said to be *mutable*; objects whose value is ' |
| 6723 | 'unchangeable\n' |
| 6724 | 'once they are created are called *immutable*. (The value of an\n' |
| 6725 | 'immutable container object that contains a reference to a ' |
| 6726 | 'mutable\n' |
| 6727 | "object can change when the latter's value is changed; however " |
| 6728 | 'the\n' |
| 6729 | 'container is still considered immutable, because the collection ' |
| 6730 | 'of\n' |
| 6731 | 'objects it contains cannot be changed. So, immutability is not\n' |
| 6732 | 'strictly the same as having an unchangeable value, it is more ' |
| 6733 | 'subtle.)\n' |
| 6734 | "An object's mutability is determined by its type; for instance,\n" |
| 6735 | 'numbers, strings and tuples are immutable, while dictionaries ' |
| 6736 | 'and\n' |
| 6737 | 'lists are mutable.\n' |
| 6738 | '\n' |
| 6739 | 'Objects are never explicitly destroyed; however, when they ' |
| 6740 | 'become\n' |
| 6741 | 'unreachable they may be garbage-collected. An implementation is\n' |
| 6742 | 'allowed to postpone garbage collection or omit it altogether --- ' |
| 6743 | 'it is\n' |
| 6744 | 'a matter of implementation quality how garbage collection is\n' |
| 6745 | 'implemented, as long as no objects are collected that are still\n' |
| 6746 | 'reachable.\n' |
| 6747 | '\n' |
| 6748 | '**CPython implementation detail:** CPython currently uses a ' |
| 6749 | 'reference-\n' |
| 6750 | 'counting scheme with (optional) delayed detection of cyclically ' |
| 6751 | 'linked\n' |
| 6752 | 'garbage, which collects most objects as soon as they become\n' |
| 6753 | 'unreachable, but is not guaranteed to collect garbage containing\n' |
| 6754 | 'circular references. See the documentation of the "gc" module ' |
| 6755 | 'for\n' |
| 6756 | 'information on controlling the collection of cyclic garbage. ' |
| 6757 | 'Other\n' |
| 6758 | 'implementations act differently and CPython may change. Do not ' |
| 6759 | 'depend\n' |
| 6760 | 'on immediate finalization of objects when they become unreachable ' |
| 6761 | '(so\n' |
| 6762 | 'you should always close files explicitly).\n' |
| 6763 | '\n' |
| 6764 | "Note that the use of the implementation's tracing or debugging\n" |
| 6765 | 'facilities may keep objects alive that would normally be ' |
| 6766 | 'collectable.\n' |
| 6767 | 'Also note that catching an exception with a \'"try"..."except"\'\n' |
| 6768 | 'statement may keep objects alive.\n' |
| 6769 | '\n' |
| 6770 | 'Some objects contain references to "external" resources such as ' |
| 6771 | 'open\n' |
| 6772 | 'files or windows. It is understood that these resources are ' |
| 6773 | 'freed\n' |
| 6774 | 'when the object is garbage-collected, but since garbage ' |
| 6775 | 'collection is\n' |
| 6776 | 'not guaranteed to happen, such objects also provide an explicit ' |
| 6777 | 'way to\n' |
| 6778 | 'release the external resource, usually a "close()" method. ' |
| 6779 | 'Programs\n' |
| 6780 | 'are strongly recommended to explicitly close such objects. The\n' |
| 6781 | '\'"try"..."finally"\' statement and the \'"with"\' statement ' |
| 6782 | 'provide\n' |
| 6783 | 'convenient ways to do this.\n' |
| 6784 | '\n' |
| 6785 | 'Some objects contain references to other objects; these are ' |
| 6786 | 'called\n' |
| 6787 | '*containers*. Examples of containers are tuples, lists and\n' |
| 6788 | "dictionaries. The references are part of a container's value. " |
| 6789 | 'In\n' |
| 6790 | 'most cases, when we talk about the value of a container, we imply ' |
| 6791 | 'the\n' |
| 6792 | 'values, not the identities of the contained objects; however, ' |
| 6793 | 'when we\n' |
| 6794 | 'talk about the mutability of a container, only the identities of ' |
| 6795 | 'the\n' |
| 6796 | 'immediately contained objects are implied. So, if an immutable\n' |
| 6797 | 'container (like a tuple) contains a reference to a mutable ' |
| 6798 | 'object, its\n' |
| 6799 | 'value changes if that mutable object is changed.\n' |
| 6800 | '\n' |
| 6801 | 'Types affect almost all aspects of object behavior. Even the\n' |
| 6802 | 'importance of object identity is affected in some sense: for ' |
| 6803 | 'immutable\n' |
| 6804 | 'types, operations that compute new values may actually return a\n' |
| 6805 | 'reference to any existing object with the same type and value, ' |
| 6806 | 'while\n' |
| 6807 | 'for mutable objects this is not allowed. E.g., after "a = 1; b = ' |
| 6808 | '1",\n' |
| 6809 | '"a" and "b" may or may not refer to the same object with the ' |
| 6810 | 'value\n' |
| 6811 | 'one, depending on the implementation, but after "c = []; d = []", ' |
| 6812 | '"c"\n' |
| 6813 | 'and "d" are guaranteed to refer to two different, unique, newly\n' |
| 6814 | 'created empty lists. (Note that "c = d = []" assigns the same ' |
| 6815 | 'object\n' |
| 6816 | 'to both "c" and "d".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6817 | 'operator-summary': 'Operator precedence\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6818 | '*******************\n' |
| 6819 | '\n' |
| 6820 | 'The following table summarizes the operator precedence ' |
| 6821 | 'in Python, from\n' |
| 6822 | 'lowest precedence (least binding) to highest precedence ' |
| 6823 | '(most\n' |
| 6824 | 'binding). Operators in the same box have the same ' |
| 6825 | 'precedence. Unless\n' |
| 6826 | 'the syntax is explicitly given, operators are binary. ' |
| 6827 | 'Operators in\n' |
| 6828 | 'the same box group left to right (except for ' |
| 6829 | 'exponentiation, which\n' |
| 6830 | 'groups from right to left).\n' |
| 6831 | '\n' |
| 6832 | 'Note that comparisons, membership tests, and identity ' |
| 6833 | 'tests, all have\n' |
| 6834 | 'the same precedence and have a left-to-right chaining ' |
| 6835 | 'feature as\n' |
| 6836 | 'described in the Comparisons section.\n' |
| 6837 | '\n' |
| 6838 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6839 | '| Operator | ' |
| 6840 | 'Description |\n' |
| 6841 | '+=================================================+=======================================+\n' |
| 6842 | '| "lambda" | ' |
| 6843 | 'Lambda expression |\n' |
| 6844 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6845 | '| "if" -- "else" | ' |
| 6846 | 'Conditional expression |\n' |
| 6847 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6848 | '| "or" | ' |
| 6849 | 'Boolean OR |\n' |
| 6850 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6851 | '| "and" | ' |
| 6852 | 'Boolean AND |\n' |
| 6853 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6854 | '| "not" "x" | ' |
| 6855 | 'Boolean NOT |\n' |
| 6856 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6857 | '| "in", "not in", "is", "is not", "<", "<=", ">", | ' |
| 6858 | 'Comparisons, including membership |\n' |
| 6859 | '| ">=", "!=", "==" | ' |
| 6860 | 'tests and identity tests |\n' |
| 6861 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6862 | '| "|" | ' |
| 6863 | 'Bitwise OR |\n' |
| 6864 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6865 | '| "^" | ' |
| 6866 | 'Bitwise XOR |\n' |
| 6867 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6868 | '| "&" | ' |
| 6869 | 'Bitwise AND |\n' |
| 6870 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6871 | '| "<<", ">>" | ' |
| 6872 | 'Shifts |\n' |
| 6873 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6874 | '| "+", "-" | ' |
| 6875 | 'Addition and subtraction |\n' |
| 6876 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6877 | '| "*", "@", "/", "//", "%" | ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6878 | 'Multiplication, matrix |\n' |
| 6879 | '| | ' |
| 6880 | 'multiplication, division, floor |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6881 | '| | ' |
| 6882 | 'division, remainder [5] |\n' |
| 6883 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6884 | '| "+x", "-x", "~x" | ' |
| 6885 | 'Positive, negative, bitwise NOT |\n' |
| 6886 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6887 | '| "**" | ' |
| 6888 | 'Exponentiation [6] |\n' |
| 6889 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6890 | '| "await" "x" | ' |
| 6891 | 'Await expression |\n' |
| 6892 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6893 | '| "x[index]", "x[index:index]", | ' |
| 6894 | 'Subscription, slicing, call, |\n' |
| 6895 | '| "x(arguments...)", "x.attribute" | ' |
| 6896 | 'attribute reference |\n' |
| 6897 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6898 | '| "(expressions...)", "[expressions...]", "{key: | ' |
| 6899 | 'Binding or tuple display, list |\n' |
| 6900 | '| value...}", "{expressions...}" | ' |
| 6901 | 'display, dictionary display, set |\n' |
| 6902 | '| | ' |
| 6903 | 'display |\n' |
| 6904 | '+-------------------------------------------------+---------------------------------------+\n' |
| 6905 | '\n' |
| 6906 | '-[ Footnotes ]-\n' |
| 6907 | '\n' |
| 6908 | '[1] While "abs(x%y) < abs(y)" is true mathematically, ' |
| 6909 | 'for floats\n' |
| 6910 | ' it may not be true numerically due to roundoff. For ' |
| 6911 | 'example, and\n' |
| 6912 | ' assuming a platform on which a Python float is an ' |
| 6913 | 'IEEE 754 double-\n' |
| 6914 | ' precision number, in order that "-1e-100 % 1e100" ' |
| 6915 | 'have the same\n' |
| 6916 | ' sign as "1e100", the computed result is "-1e-100 + ' |
| 6917 | '1e100", which\n' |
| 6918 | ' is numerically exactly equal to "1e100". The ' |
| 6919 | 'function\n' |
| 6920 | ' "math.fmod()" returns a result whose sign matches ' |
| 6921 | 'the sign of the\n' |
| 6922 | ' first argument instead, and so returns "-1e-100" in ' |
| 6923 | 'this case.\n' |
| 6924 | ' Which approach is more appropriate depends on the ' |
| 6925 | 'application.\n' |
| 6926 | '\n' |
| 6927 | '[2] If x is very close to an exact integer multiple of ' |
| 6928 | "y, it's\n" |
| 6929 | ' possible for "x//y" to be one larger than ' |
| 6930 | '"(x-x%y)//y" due to\n' |
| 6931 | ' rounding. In such cases, Python returns the latter ' |
| 6932 | 'result, in\n' |
| 6933 | ' order to preserve that "divmod(x,y)[0] * y + x % y" ' |
| 6934 | 'be very close\n' |
| 6935 | ' to "x".\n' |
| 6936 | '\n' |
| 6937 | '[3] The Unicode standard distinguishes between *code ' |
| 6938 | 'points* (e.g.\n' |
| 6939 | ' U+0041) and *abstract characters* (e.g. "LATIN ' |
| 6940 | 'CAPITAL LETTER A").\n' |
| 6941 | ' While most abstract characters in Unicode are only ' |
| 6942 | 'represented\n' |
| 6943 | ' using one code point, there is a number of abstract ' |
| 6944 | 'characters\n' |
| 6945 | ' that can in addition be represented using a sequence ' |
| 6946 | 'of more than\n' |
| 6947 | ' one code point. For example, the abstract character ' |
| 6948 | '"LATIN\n' |
| 6949 | ' CAPITAL LETTER C WITH CEDILLA" can be represented as ' |
| 6950 | 'a single\n' |
| 6951 | ' *precomposed character* at code position U+00C7, or ' |
| 6952 | 'as a sequence\n' |
| 6953 | ' of a *base character* at code position U+0043 (LATIN ' |
| 6954 | 'CAPITAL\n' |
| 6955 | ' LETTER C), followed by a *combining character* at ' |
| 6956 | 'code position\n' |
| 6957 | ' U+0327 (COMBINING CEDILLA).\n' |
| 6958 | '\n' |
| 6959 | ' The comparison operators on strings compare at the ' |
| 6960 | 'level of\n' |
| 6961 | ' Unicode code points. This may be counter-intuitive ' |
| 6962 | 'to humans. For\n' |
| 6963 | ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", ' |
| 6964 | 'even though both\n' |
| 6965 | ' strings represent the same abstract character "LATIN ' |
| 6966 | 'CAPITAL\n' |
| 6967 | ' LETTER C WITH CEDILLA".\n' |
| 6968 | '\n' |
| 6969 | ' To compare strings at the level of abstract ' |
| 6970 | 'characters (that is,\n' |
| 6971 | ' in a way intuitive to humans), use ' |
| 6972 | '"unicodedata.normalize()".\n' |
| 6973 | '\n' |
| 6974 | '[4] Due to automatic garbage-collection, free lists, and ' |
| 6975 | 'the\n' |
| 6976 | ' dynamic nature of descriptors, you may notice ' |
| 6977 | 'seemingly unusual\n' |
| 6978 | ' behaviour in certain uses of the "is" operator, like ' |
| 6979 | 'those\n' |
| 6980 | ' involving comparisons between instance methods, or ' |
| 6981 | 'constants.\n' |
| 6982 | ' Check their documentation for more info.\n' |
| 6983 | '\n' |
| 6984 | '[5] The "%" operator is also used for string formatting; ' |
| 6985 | 'the same\n' |
| 6986 | ' precedence applies.\n' |
| 6987 | '\n' |
| 6988 | '[6] The power operator "**" binds less tightly than an ' |
| 6989 | 'arithmetic\n' |
| 6990 | ' or bitwise unary operator on its right, that is, ' |
| 6991 | '"2**-1" is "0.5".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 6992 | 'pass': 'The "pass" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 6993 | '********************\n' |
| 6994 | '\n' |
| 6995 | ' pass_stmt ::= "pass"\n' |
| 6996 | '\n' |
| 6997 | '"pass" is a null operation --- when it is executed, nothing ' |
| 6998 | 'happens.\n' |
| 6999 | 'It is useful as a placeholder when a statement is required\n' |
| 7000 | 'syntactically, but no code needs to be executed, for example:\n' |
| 7001 | '\n' |
| 7002 | ' def f(arg): pass # a function that does nothing (yet)\n' |
| 7003 | '\n' |
| 7004 | ' class C: pass # a class with no methods (yet)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7005 | 'power': 'The power operator\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7006 | '******************\n' |
| 7007 | '\n' |
| 7008 | 'The power operator binds more tightly than unary operators on its\n' |
| 7009 | 'left; it binds less tightly than unary operators on its right. ' |
| 7010 | 'The\n' |
| 7011 | 'syntax is:\n' |
| 7012 | '\n' |
| 7013 | ' power ::= ( await_expr | primary ) ["**" u_expr]\n' |
| 7014 | '\n' |
| 7015 | 'Thus, in an unparenthesized sequence of power and unary operators, ' |
| 7016 | 'the\n' |
| 7017 | 'operators are evaluated from right to left (this does not ' |
| 7018 | 'constrain\n' |
| 7019 | 'the evaluation order for the operands): "-1**2" results in "-1".\n' |
| 7020 | '\n' |
| 7021 | 'The power operator has the same semantics as the built-in "pow()"\n' |
| 7022 | 'function, when called with two arguments: it yields its left ' |
| 7023 | 'argument\n' |
| 7024 | 'raised to the power of its right argument. The numeric arguments ' |
| 7025 | 'are\n' |
| 7026 | 'first converted to a common type, and the result is of that type.\n' |
| 7027 | '\n' |
| 7028 | 'For int operands, the result has the same type as the operands ' |
| 7029 | 'unless\n' |
| 7030 | 'the second argument is negative; in that case, all arguments are\n' |
| 7031 | 'converted to float and a float result is delivered. For example,\n' |
| 7032 | '"10**2" returns "100", but "10**-2" returns "0.01".\n' |
| 7033 | '\n' |
| 7034 | 'Raising "0.0" to a negative power results in a ' |
| 7035 | '"ZeroDivisionError".\n' |
| 7036 | 'Raising a negative number to a fractional power results in a ' |
| 7037 | '"complex"\n' |
| 7038 | 'number. (In earlier versions it raised a "ValueError".)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7039 | 'raise': 'The "raise" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7040 | '*********************\n' |
| 7041 | '\n' |
| 7042 | ' raise_stmt ::= "raise" [expression ["from" expression]]\n' |
| 7043 | '\n' |
| 7044 | 'If no expressions are present, "raise" re-raises the last ' |
| 7045 | 'exception\n' |
| 7046 | 'that was active in the current scope. If no exception is active ' |
| 7047 | 'in\n' |
| 7048 | 'the current scope, a "RuntimeError" exception is raised indicating\n' |
| 7049 | 'that this is an error.\n' |
| 7050 | '\n' |
| 7051 | 'Otherwise, "raise" evaluates the first expression as the exception\n' |
| 7052 | 'object. It must be either a subclass or an instance of\n' |
| 7053 | '"BaseException". If it is a class, the exception instance will be\n' |
| 7054 | 'obtained when needed by instantiating the class with no arguments.\n' |
| 7055 | '\n' |
| 7056 | "The *type* of the exception is the exception instance's class, the\n" |
| 7057 | '*value* is the instance itself.\n' |
| 7058 | '\n' |
| 7059 | 'A traceback object is normally created automatically when an ' |
| 7060 | 'exception\n' |
| 7061 | 'is raised and attached to it as the "__traceback__" attribute, ' |
| 7062 | 'which\n' |
| 7063 | 'is writable. You can create an exception and set your own traceback ' |
| 7064 | 'in\n' |
| 7065 | 'one step using the "with_traceback()" exception method (which ' |
| 7066 | 'returns\n' |
| 7067 | 'the same exception instance, with its traceback set to its ' |
| 7068 | 'argument),\n' |
| 7069 | 'like so:\n' |
| 7070 | '\n' |
| 7071 | ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' |
| 7072 | '\n' |
| 7073 | 'The "from" clause is used for exception chaining: if given, the ' |
| 7074 | 'second\n' |
| 7075 | '*expression* must be another exception class or instance, which ' |
| 7076 | 'will\n' |
| 7077 | 'then be attached to the raised exception as the "__cause__" ' |
| 7078 | 'attribute\n' |
| 7079 | '(which is writable). If the raised exception is not handled, both\n' |
| 7080 | 'exceptions will be printed:\n' |
| 7081 | '\n' |
| 7082 | ' >>> try:\n' |
| 7083 | ' ... print(1 / 0)\n' |
| 7084 | ' ... except Exception as exc:\n' |
| 7085 | ' ... raise RuntimeError("Something bad happened") from exc\n' |
| 7086 | ' ...\n' |
| 7087 | ' Traceback (most recent call last):\n' |
| 7088 | ' File "<stdin>", line 2, in <module>\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7089 | ' ZeroDivisionError: division by zero\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7090 | '\n' |
| 7091 | ' The above exception was the direct cause of the following ' |
| 7092 | 'exception:\n' |
| 7093 | '\n' |
| 7094 | ' Traceback (most recent call last):\n' |
| 7095 | ' File "<stdin>", line 4, in <module>\n' |
| 7096 | ' RuntimeError: Something bad happened\n' |
| 7097 | '\n' |
| 7098 | 'A similar mechanism works implicitly if an exception is raised ' |
| 7099 | 'inside\n' |
| 7100 | 'an exception handler or a "finally" clause: the previous exception ' |
| 7101 | 'is\n' |
| 7102 | 'then attached as the new exception\'s "__context__" attribute:\n' |
| 7103 | '\n' |
| 7104 | ' >>> try:\n' |
| 7105 | ' ... print(1 / 0)\n' |
| 7106 | ' ... except:\n' |
| 7107 | ' ... raise RuntimeError("Something bad happened")\n' |
| 7108 | ' ...\n' |
| 7109 | ' Traceback (most recent call last):\n' |
| 7110 | ' File "<stdin>", line 2, in <module>\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7111 | ' ZeroDivisionError: division by zero\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7112 | '\n' |
| 7113 | ' During handling of the above exception, another exception ' |
| 7114 | 'occurred:\n' |
| 7115 | '\n' |
| 7116 | ' Traceback (most recent call last):\n' |
| 7117 | ' File "<stdin>", line 4, in <module>\n' |
| 7118 | ' RuntimeError: Something bad happened\n' |
| 7119 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7120 | 'Exception chaining can be explicitly suppressed by specifying ' |
| 7121 | '"None"\n' |
| 7122 | 'in the "from" clause:\n' |
| 7123 | '\n' |
| 7124 | ' >>> try:\n' |
| 7125 | ' ... print(1 / 0)\n' |
| 7126 | ' ... except:\n' |
| 7127 | ' ... raise RuntimeError("Something bad happened") from None\n' |
| 7128 | ' ...\n' |
| 7129 | ' Traceback (most recent call last):\n' |
| 7130 | ' File "<stdin>", line 4, in <module>\n' |
| 7131 | ' RuntimeError: Something bad happened\n' |
| 7132 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7133 | 'Additional information on exceptions can be found in section\n' |
| 7134 | 'Exceptions, and information about handling exceptions is in ' |
| 7135 | 'section\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7136 | 'The try statement.\n' |
| 7137 | '\n' |
| 7138 | 'Changed in version 3.3: "None" is now permitted as "Y" in "raise X\n' |
| 7139 | 'from Y".\n' |
| 7140 | '\n' |
| 7141 | 'New in version 3.3: The "__suppress_context__" attribute to ' |
| 7142 | 'suppress\n' |
| 7143 | 'automatic display of the exception context.\n', |
| 7144 | 'return': 'The "return" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7145 | '**********************\n' |
| 7146 | '\n' |
| 7147 | ' return_stmt ::= "return" [expression_list]\n' |
| 7148 | '\n' |
| 7149 | '"return" may only occur syntactically nested in a function ' |
| 7150 | 'definition,\n' |
| 7151 | 'not within a nested class definition.\n' |
| 7152 | '\n' |
| 7153 | 'If an expression list is present, it is evaluated, else "None" is\n' |
| 7154 | 'substituted.\n' |
| 7155 | '\n' |
| 7156 | '"return" leaves the current function call with the expression list ' |
| 7157 | '(or\n' |
| 7158 | '"None") as return value.\n' |
| 7159 | '\n' |
| 7160 | 'When "return" passes control out of a "try" statement with a ' |
| 7161 | '"finally"\n' |
| 7162 | 'clause, that "finally" clause is executed before really leaving ' |
| 7163 | 'the\n' |
| 7164 | 'function.\n' |
| 7165 | '\n' |
| 7166 | 'In a generator function, the "return" statement indicates that ' |
| 7167 | 'the\n' |
| 7168 | 'generator is done and will cause "StopIteration" to be raised. ' |
| 7169 | 'The\n' |
| 7170 | 'returned value (if any) is used as an argument to construct\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7171 | '"StopIteration" and becomes the "StopIteration.value" attribute.\n' |
| 7172 | '\n' |
| 7173 | 'In an asynchronous generator function, an empty "return" ' |
| 7174 | 'statement\n' |
| 7175 | 'indicates that the asynchronous generator is done and will cause\n' |
| 7176 | '"StopAsyncIteration" to be raised. A non-empty "return" statement ' |
| 7177 | 'is\n' |
| 7178 | 'a syntax error in an asynchronous generator function.\n', |
| 7179 | 'sequence-types': 'Emulating container types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7180 | '*************************\n' |
| 7181 | '\n' |
| 7182 | 'The following methods can be defined to implement ' |
| 7183 | 'container objects.\n' |
| 7184 | 'Containers usually are sequences (such as lists or tuples) ' |
| 7185 | 'or mappings\n' |
| 7186 | '(like dictionaries), but can represent other containers as ' |
| 7187 | 'well. The\n' |
| 7188 | 'first set of methods is used either to emulate a sequence ' |
| 7189 | 'or to\n' |
| 7190 | 'emulate a mapping; the difference is that for a sequence, ' |
| 7191 | 'the\n' |
| 7192 | 'allowable keys should be the integers *k* for which "0 <= ' |
| 7193 | 'k < N" where\n' |
| 7194 | '*N* is the length of the sequence, or slice objects, which ' |
| 7195 | 'define a\n' |
| 7196 | 'range of items. It is also recommended that mappings ' |
| 7197 | 'provide the\n' |
| 7198 | 'methods "keys()", "values()", "items()", "get()", ' |
| 7199 | '"clear()",\n' |
| 7200 | '"setdefault()", "pop()", "popitem()", "copy()", and ' |
| 7201 | '"update()"\n' |
| 7202 | "behaving similar to those for Python's standard dictionary " |
| 7203 | 'objects.\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7204 | 'The "collections.abc" module provides a "MutableMapping" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7205 | 'abstract base\n' |
| 7206 | 'class to help create those methods from a base set of ' |
| 7207 | '"__getitem__()",\n' |
| 7208 | '"__setitem__()", "__delitem__()", and "keys()". Mutable ' |
| 7209 | 'sequences\n' |
| 7210 | 'should provide methods "append()", "count()", "index()", ' |
| 7211 | '"extend()",\n' |
| 7212 | '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' |
| 7213 | 'like Python\n' |
| 7214 | 'standard list objects. Finally, sequence types should ' |
| 7215 | 'implement\n' |
| 7216 | 'addition (meaning concatenation) and multiplication ' |
| 7217 | '(meaning\n' |
| 7218 | 'repetition) by defining the methods "__add__()", ' |
| 7219 | '"__radd__()",\n' |
| 7220 | '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' |
| 7221 | 'described\n' |
| 7222 | 'below; they should not define other numerical operators. ' |
| 7223 | 'It is\n' |
| 7224 | 'recommended that both mappings and sequences implement ' |
| 7225 | 'the\n' |
| 7226 | '"__contains__()" method to allow efficient use of the "in" ' |
| 7227 | 'operator;\n' |
| 7228 | 'for mappings, "in" should search the mapping\'s keys; for ' |
| 7229 | 'sequences, it\n' |
| 7230 | 'should search through the values. It is further ' |
| 7231 | 'recommended that both\n' |
| 7232 | 'mappings and sequences implement the "__iter__()" method ' |
| 7233 | 'to allow\n' |
| 7234 | 'efficient iteration through the container; for mappings, ' |
| 7235 | '"__iter__()"\n' |
| 7236 | 'should be the same as "keys()"; for sequences, it should ' |
| 7237 | 'iterate\n' |
| 7238 | 'through the values.\n' |
| 7239 | '\n' |
| 7240 | 'object.__len__(self)\n' |
| 7241 | '\n' |
| 7242 | ' Called to implement the built-in function "len()". ' |
| 7243 | 'Should return\n' |
| 7244 | ' the length of the object, an integer ">=" 0. Also, an ' |
| 7245 | 'object that\n' |
| 7246 | ' doesn\'t define a "__bool__()" method and whose ' |
| 7247 | '"__len__()" method\n' |
| 7248 | ' returns zero is considered to be false in a Boolean ' |
| 7249 | 'context.\n' |
| 7250 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7251 | ' **CPython implementation detail:** In CPython, the ' |
| 7252 | 'length is\n' |
| 7253 | ' required to be at most "sys.maxsize". If the length is ' |
| 7254 | 'larger than\n' |
| 7255 | ' "sys.maxsize" some features (such as "len()") may ' |
| 7256 | 'raise\n' |
| 7257 | ' "OverflowError". To prevent raising "OverflowError" by ' |
| 7258 | 'truth value\n' |
| 7259 | ' testing, an object must define a "__bool__()" method.\n' |
| 7260 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7261 | 'object.__length_hint__(self)\n' |
| 7262 | '\n' |
| 7263 | ' Called to implement "operator.length_hint()". Should ' |
| 7264 | 'return an\n' |
| 7265 | ' estimated length for the object (which may be greater ' |
| 7266 | 'or less than\n' |
| 7267 | ' the actual length). The length must be an integer ">=" ' |
| 7268 | '0. This\n' |
| 7269 | ' method is purely an optimization and is never required ' |
| 7270 | 'for\n' |
| 7271 | ' correctness.\n' |
| 7272 | '\n' |
| 7273 | ' New in version 3.4.\n' |
| 7274 | '\n' |
| 7275 | 'Note: Slicing is done exclusively with the following three ' |
| 7276 | 'methods.\n' |
| 7277 | ' A call like\n' |
| 7278 | '\n' |
| 7279 | ' a[1:2] = b\n' |
| 7280 | '\n' |
| 7281 | ' is translated to\n' |
| 7282 | '\n' |
| 7283 | ' a[slice(1, 2, None)] = b\n' |
| 7284 | '\n' |
| 7285 | ' and so forth. Missing slice items are always filled in ' |
| 7286 | 'with "None".\n' |
| 7287 | '\n' |
| 7288 | 'object.__getitem__(self, key)\n' |
| 7289 | '\n' |
| 7290 | ' Called to implement evaluation of "self[key]". For ' |
| 7291 | 'sequence types,\n' |
| 7292 | ' the accepted keys should be integers and slice ' |
| 7293 | 'objects. Note that\n' |
| 7294 | ' the special interpretation of negative indexes (if the ' |
| 7295 | 'class wishes\n' |
| 7296 | ' to emulate a sequence type) is up to the ' |
| 7297 | '"__getitem__()" method. If\n' |
| 7298 | ' *key* is of an inappropriate type, "TypeError" may be ' |
| 7299 | 'raised; if of\n' |
| 7300 | ' a value outside the set of indexes for the sequence ' |
| 7301 | '(after any\n' |
| 7302 | ' special interpretation of negative values), ' |
| 7303 | '"IndexError" should be\n' |
| 7304 | ' raised. For mapping types, if *key* is missing (not in ' |
| 7305 | 'the\n' |
| 7306 | ' container), "KeyError" should be raised.\n' |
| 7307 | '\n' |
| 7308 | ' Note: "for" loops expect that an "IndexError" will be ' |
| 7309 | 'raised for\n' |
| 7310 | ' illegal indexes to allow proper detection of the end ' |
| 7311 | 'of the\n' |
| 7312 | ' sequence.\n' |
| 7313 | '\n' |
| 7314 | 'object.__missing__(self, key)\n' |
| 7315 | '\n' |
| 7316 | ' Called by "dict"."__getitem__()" to implement ' |
| 7317 | '"self[key]" for dict\n' |
| 7318 | ' subclasses when key is not in the dictionary.\n' |
| 7319 | '\n' |
| 7320 | 'object.__setitem__(self, key, value)\n' |
| 7321 | '\n' |
| 7322 | ' Called to implement assignment to "self[key]". Same ' |
| 7323 | 'note as for\n' |
| 7324 | ' "__getitem__()". This should only be implemented for ' |
| 7325 | 'mappings if\n' |
| 7326 | ' the objects support changes to the values for keys, or ' |
| 7327 | 'if new keys\n' |
| 7328 | ' can be added, or for sequences if elements can be ' |
| 7329 | 'replaced. The\n' |
| 7330 | ' same exceptions should be raised for improper *key* ' |
| 7331 | 'values as for\n' |
| 7332 | ' the "__getitem__()" method.\n' |
| 7333 | '\n' |
| 7334 | 'object.__delitem__(self, key)\n' |
| 7335 | '\n' |
| 7336 | ' Called to implement deletion of "self[key]". Same note ' |
| 7337 | 'as for\n' |
| 7338 | ' "__getitem__()". This should only be implemented for ' |
| 7339 | 'mappings if\n' |
| 7340 | ' the objects support removal of keys, or for sequences ' |
| 7341 | 'if elements\n' |
| 7342 | ' can be removed from the sequence. The same exceptions ' |
| 7343 | 'should be\n' |
| 7344 | ' raised for improper *key* values as for the ' |
| 7345 | '"__getitem__()" method.\n' |
| 7346 | '\n' |
| 7347 | 'object.__iter__(self)\n' |
| 7348 | '\n' |
| 7349 | ' This method is called when an iterator is required for ' |
| 7350 | 'a container.\n' |
| 7351 | ' This method should return a new iterator object that ' |
| 7352 | 'can iterate\n' |
| 7353 | ' over all the objects in the container. For mappings, ' |
| 7354 | 'it should\n' |
| 7355 | ' iterate over the keys of the container.\n' |
| 7356 | '\n' |
| 7357 | ' Iterator objects also need to implement this method; ' |
| 7358 | 'they are\n' |
| 7359 | ' required to return themselves. For more information on ' |
| 7360 | 'iterator\n' |
| 7361 | ' objects, see Iterator Types.\n' |
| 7362 | '\n' |
| 7363 | 'object.__reversed__(self)\n' |
| 7364 | '\n' |
| 7365 | ' Called (if present) by the "reversed()" built-in to ' |
| 7366 | 'implement\n' |
| 7367 | ' reverse iteration. It should return a new iterator ' |
| 7368 | 'object that\n' |
| 7369 | ' iterates over all the objects in the container in ' |
| 7370 | 'reverse order.\n' |
| 7371 | '\n' |
| 7372 | ' If the "__reversed__()" method is not provided, the ' |
| 7373 | '"reversed()"\n' |
| 7374 | ' built-in will fall back to using the sequence protocol ' |
| 7375 | '("__len__()"\n' |
| 7376 | ' and "__getitem__()"). Objects that support the ' |
| 7377 | 'sequence protocol\n' |
| 7378 | ' should only provide "__reversed__()" if they can ' |
| 7379 | 'provide an\n' |
| 7380 | ' implementation that is more efficient than the one ' |
| 7381 | 'provided by\n' |
| 7382 | ' "reversed()".\n' |
| 7383 | '\n' |
| 7384 | 'The membership test operators ("in" and "not in") are ' |
| 7385 | 'normally\n' |
| 7386 | 'implemented as an iteration through a sequence. However, ' |
| 7387 | 'container\n' |
| 7388 | 'objects can supply the following special method with a ' |
| 7389 | 'more efficient\n' |
| 7390 | 'implementation, which also does not require the object be ' |
| 7391 | 'a sequence.\n' |
| 7392 | '\n' |
| 7393 | 'object.__contains__(self, item)\n' |
| 7394 | '\n' |
| 7395 | ' Called to implement membership test operators. Should ' |
| 7396 | 'return true\n' |
| 7397 | ' if *item* is in *self*, false otherwise. For mapping ' |
| 7398 | 'objects, this\n' |
| 7399 | ' should consider the keys of the mapping rather than the ' |
| 7400 | 'values or\n' |
| 7401 | ' the key-item pairs.\n' |
| 7402 | '\n' |
| 7403 | ' For objects that don\'t define "__contains__()", the ' |
| 7404 | 'membership test\n' |
| 7405 | ' first tries iteration via "__iter__()", then the old ' |
| 7406 | 'sequence\n' |
| 7407 | ' iteration protocol via "__getitem__()", see this ' |
| 7408 | 'section in the\n' |
| 7409 | ' language reference.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7410 | 'shifting': 'Shifting operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7411 | '*******************\n' |
| 7412 | '\n' |
| 7413 | 'The shifting operations have lower priority than the arithmetic\n' |
| 7414 | 'operations:\n' |
| 7415 | '\n' |
| 7416 | ' shift_expr ::= a_expr | shift_expr ( "<<" | ">>" ) a_expr\n' |
| 7417 | '\n' |
| 7418 | 'These operators accept integers as arguments. They shift the ' |
| 7419 | 'first\n' |
| 7420 | 'argument to the left or right by the number of bits given by ' |
| 7421 | 'the\n' |
| 7422 | 'second argument.\n' |
| 7423 | '\n' |
| 7424 | 'A right shift by *n* bits is defined as floor division by ' |
| 7425 | '"pow(2,n)".\n' |
| 7426 | 'A left shift by *n* bits is defined as multiplication with ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7427 | '"pow(2,n)".\n', |
| 7428 | 'slicings': 'Slicings\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7429 | '********\n' |
| 7430 | '\n' |
| 7431 | 'A slicing selects a range of items in a sequence object (e.g., ' |
| 7432 | 'a\n' |
| 7433 | 'string, tuple or list). Slicings may be used as expressions or ' |
| 7434 | 'as\n' |
| 7435 | 'targets in assignment or "del" statements. The syntax for a ' |
| 7436 | 'slicing:\n' |
| 7437 | '\n' |
| 7438 | ' slicing ::= primary "[" slice_list "]"\n' |
| 7439 | ' slice_list ::= slice_item ("," slice_item)* [","]\n' |
| 7440 | ' slice_item ::= expression | proper_slice\n' |
| 7441 | ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" ' |
| 7442 | '[stride] ]\n' |
| 7443 | ' lower_bound ::= expression\n' |
| 7444 | ' upper_bound ::= expression\n' |
| 7445 | ' stride ::= expression\n' |
| 7446 | '\n' |
| 7447 | 'There is ambiguity in the formal syntax here: anything that ' |
| 7448 | 'looks like\n' |
| 7449 | 'an expression list also looks like a slice list, so any ' |
| 7450 | 'subscription\n' |
| 7451 | 'can be interpreted as a slicing. Rather than further ' |
| 7452 | 'complicating the\n' |
| 7453 | 'syntax, this is disambiguated by defining that in this case the\n' |
| 7454 | 'interpretation as a subscription takes priority over the\n' |
| 7455 | 'interpretation as a slicing (this is the case if the slice list\n' |
| 7456 | 'contains no proper slice).\n' |
| 7457 | '\n' |
| 7458 | 'The semantics for a slicing are as follows. The primary is ' |
| 7459 | 'indexed\n' |
| 7460 | '(using the same "__getitem__()" method as normal subscription) ' |
| 7461 | 'with a\n' |
| 7462 | 'key that is constructed from the slice list, as follows. If the ' |
| 7463 | 'slice\n' |
| 7464 | 'list contains at least one comma, the key is a tuple containing ' |
| 7465 | 'the\n' |
| 7466 | 'conversion of the slice items; otherwise, the conversion of the ' |
| 7467 | 'lone\n' |
| 7468 | 'slice item is the key. The conversion of a slice item that is ' |
| 7469 | 'an\n' |
| 7470 | 'expression is that expression. The conversion of a proper slice ' |
| 7471 | 'is a\n' |
| 7472 | 'slice object (see section The standard type hierarchy) whose ' |
| 7473 | '"start",\n' |
| 7474 | '"stop" and "step" attributes are the values of the expressions ' |
| 7475 | 'given\n' |
| 7476 | 'as lower bound, upper bound and stride, respectively, ' |
| 7477 | 'substituting\n' |
| 7478 | '"None" for missing expressions.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7479 | 'specialattrs': 'Special Attributes\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7480 | '******************\n' |
| 7481 | '\n' |
| 7482 | 'The implementation adds a few special read-only attributes ' |
| 7483 | 'to several\n' |
| 7484 | 'object types, where they are relevant. Some of these are ' |
| 7485 | 'not reported\n' |
| 7486 | 'by the "dir()" built-in function.\n' |
| 7487 | '\n' |
| 7488 | 'object.__dict__\n' |
| 7489 | '\n' |
| 7490 | ' A dictionary or other mapping object used to store an ' |
| 7491 | "object's\n" |
| 7492 | ' (writable) attributes.\n' |
| 7493 | '\n' |
| 7494 | 'instance.__class__\n' |
| 7495 | '\n' |
| 7496 | ' The class to which a class instance belongs.\n' |
| 7497 | '\n' |
| 7498 | 'class.__bases__\n' |
| 7499 | '\n' |
| 7500 | ' The tuple of base classes of a class object.\n' |
| 7501 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7502 | 'definition.__name__\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7503 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7504 | ' The name of the class, function, method, descriptor, or ' |
| 7505 | 'generator\n' |
| 7506 | ' instance.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7507 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7508 | 'definition.__qualname__\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7509 | '\n' |
Ned Deily | aa843d2 | 2016-07-11 15:32:48 -0400 | [diff] [blame] | 7510 | ' The *qualified name* of the class, function, method, ' |
| 7511 | 'descriptor, or\n' |
| 7512 | ' generator instance.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7513 | '\n' |
| 7514 | ' New in version 3.3.\n' |
| 7515 | '\n' |
| 7516 | 'class.__mro__\n' |
| 7517 | '\n' |
| 7518 | ' This attribute is a tuple of classes that are considered ' |
| 7519 | 'when\n' |
| 7520 | ' looking for base classes during method resolution.\n' |
| 7521 | '\n' |
| 7522 | 'class.mro()\n' |
| 7523 | '\n' |
| 7524 | ' This method can be overridden by a metaclass to customize ' |
| 7525 | 'the\n' |
| 7526 | ' method resolution order for its instances. It is called ' |
| 7527 | 'at class\n' |
| 7528 | ' instantiation, and its result is stored in "__mro__".\n' |
| 7529 | '\n' |
| 7530 | 'class.__subclasses__()\n' |
| 7531 | '\n' |
| 7532 | ' Each class keeps a list of weak references to its ' |
| 7533 | 'immediate\n' |
| 7534 | ' subclasses. This method returns a list of all those ' |
| 7535 | 'references\n' |
| 7536 | ' still alive. Example:\n' |
| 7537 | '\n' |
| 7538 | ' >>> int.__subclasses__()\n' |
| 7539 | " [<class 'bool'>]\n" |
| 7540 | '\n' |
| 7541 | '-[ Footnotes ]-\n' |
| 7542 | '\n' |
| 7543 | '[1] Additional information on these special methods may be ' |
| 7544 | 'found\n' |
| 7545 | ' in the Python Reference Manual (Basic customization).\n' |
| 7546 | '\n' |
| 7547 | '[2] As a consequence, the list "[1, 2]" is considered equal ' |
| 7548 | 'to\n' |
| 7549 | ' "[1.0, 2.0]", and similarly for tuples.\n' |
| 7550 | '\n' |
| 7551 | "[3] They must have since the parser can't tell the type of " |
| 7552 | 'the\n' |
| 7553 | ' operands.\n' |
| 7554 | '\n' |
| 7555 | '[4] Cased characters are those with general category ' |
| 7556 | 'property\n' |
| 7557 | ' being one of "Lu" (Letter, uppercase), "Ll" (Letter, ' |
| 7558 | 'lowercase),\n' |
| 7559 | ' or "Lt" (Letter, titlecase).\n' |
| 7560 | '\n' |
| 7561 | '[5] To format only a tuple you should therefore provide a\n' |
| 7562 | ' singleton tuple whose only element is the tuple to be ' |
| 7563 | 'formatted.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7564 | 'specialnames': 'Special method names\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7565 | '********************\n' |
| 7566 | '\n' |
| 7567 | 'A class can implement certain operations that are invoked by ' |
| 7568 | 'special\n' |
| 7569 | 'syntax (such as arithmetic operations or subscripting and ' |
| 7570 | 'slicing) by\n' |
| 7571 | "defining methods with special names. This is Python's " |
| 7572 | 'approach to\n' |
| 7573 | '*operator overloading*, allowing classes to define their own ' |
| 7574 | 'behavior\n' |
| 7575 | 'with respect to language operators. For instance, if a ' |
| 7576 | 'class defines\n' |
| 7577 | 'a method named "__getitem__()", and "x" is an instance of ' |
| 7578 | 'this class,\n' |
| 7579 | 'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, ' |
| 7580 | 'i)".\n' |
| 7581 | 'Except where mentioned, attempts to execute an operation ' |
| 7582 | 'raise an\n' |
| 7583 | 'exception when no appropriate method is defined (typically\n' |
| 7584 | '"AttributeError" or "TypeError").\n' |
| 7585 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 7586 | 'Setting a special method to "None" indicates that the ' |
| 7587 | 'corresponding\n' |
| 7588 | 'operation is not available. For example, if a class sets ' |
| 7589 | '"__iter__()"\n' |
| 7590 | 'to "None", the class is not iterable, so calling "iter()" on ' |
| 7591 | 'its\n' |
| 7592 | 'instances will raise a "TypeError" (without falling back to\n' |
| 7593 | '"__getitem__()"). [2]\n' |
| 7594 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7595 | 'When implementing a class that emulates any built-in type, ' |
| 7596 | 'it is\n' |
| 7597 | 'important that the emulation only be implemented to the ' |
| 7598 | 'degree that it\n' |
| 7599 | 'makes sense for the object being modelled. For example, ' |
| 7600 | 'some\n' |
| 7601 | 'sequences may work well with retrieval of individual ' |
| 7602 | 'elements, but\n' |
| 7603 | 'extracting a slice may not make sense. (One example of this ' |
| 7604 | 'is the\n' |
| 7605 | '"NodeList" interface in the W3C\'s Document Object Model.)\n' |
| 7606 | '\n' |
| 7607 | '\n' |
| 7608 | 'Basic customization\n' |
| 7609 | '===================\n' |
| 7610 | '\n' |
| 7611 | 'object.__new__(cls[, ...])\n' |
| 7612 | '\n' |
| 7613 | ' Called to create a new instance of class *cls*. ' |
| 7614 | '"__new__()" is a\n' |
| 7615 | ' static method (special-cased so you need not declare it ' |
| 7616 | 'as such)\n' |
| 7617 | ' that takes the class of which an instance was requested ' |
| 7618 | 'as its\n' |
| 7619 | ' first argument. The remaining arguments are those passed ' |
| 7620 | 'to the\n' |
| 7621 | ' object constructor expression (the call to the class). ' |
| 7622 | 'The return\n' |
| 7623 | ' value of "__new__()" should be the new object instance ' |
| 7624 | '(usually an\n' |
| 7625 | ' instance of *cls*).\n' |
| 7626 | '\n' |
| 7627 | ' Typical implementations create a new instance of the ' |
| 7628 | 'class by\n' |
| 7629 | ' invoking the superclass\'s "__new__()" method using\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7630 | ' "super().__new__(cls[, ...])" with appropriate arguments ' |
| 7631 | 'and then\n' |
| 7632 | ' modifying the newly-created instance as necessary before ' |
| 7633 | 'returning\n' |
| 7634 | ' it.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7635 | '\n' |
| 7636 | ' If "__new__()" returns an instance of *cls*, then the ' |
| 7637 | 'new\n' |
| 7638 | ' instance\'s "__init__()" method will be invoked like\n' |
| 7639 | ' "__init__(self[, ...])", where *self* is the new instance ' |
| 7640 | 'and the\n' |
| 7641 | ' remaining arguments are the same as were passed to ' |
| 7642 | '"__new__()".\n' |
| 7643 | '\n' |
| 7644 | ' If "__new__()" does not return an instance of *cls*, then ' |
| 7645 | 'the new\n' |
| 7646 | ' instance\'s "__init__()" method will not be invoked.\n' |
| 7647 | '\n' |
| 7648 | ' "__new__()" is intended mainly to allow subclasses of ' |
| 7649 | 'immutable\n' |
| 7650 | ' types (like int, str, or tuple) to customize instance ' |
| 7651 | 'creation. It\n' |
| 7652 | ' is also commonly overridden in custom metaclasses in ' |
| 7653 | 'order to\n' |
| 7654 | ' customize class creation.\n' |
| 7655 | '\n' |
| 7656 | 'object.__init__(self[, ...])\n' |
| 7657 | '\n' |
| 7658 | ' Called after the instance has been created (by ' |
| 7659 | '"__new__()"), but\n' |
| 7660 | ' before it is returned to the caller. The arguments are ' |
| 7661 | 'those\n' |
| 7662 | ' passed to the class constructor expression. If a base ' |
| 7663 | 'class has an\n' |
| 7664 | ' "__init__()" method, the derived class\'s "__init__()" ' |
| 7665 | 'method, if\n' |
| 7666 | ' any, must explicitly call it to ensure proper ' |
| 7667 | 'initialization of the\n' |
| 7668 | ' base class part of the instance; for example:\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7669 | ' "super().__init__([args...])".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7670 | '\n' |
| 7671 | ' Because "__new__()" and "__init__()" work together in ' |
| 7672 | 'constructing\n' |
| 7673 | ' objects ("__new__()" to create it, and "__init__()" to ' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 7674 | 'customize\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7675 | ' it), no non-"None" value may be returned by "__init__()"; ' |
| 7676 | 'doing so\n' |
| 7677 | ' will cause a "TypeError" to be raised at runtime.\n' |
| 7678 | '\n' |
| 7679 | 'object.__del__(self)\n' |
| 7680 | '\n' |
| 7681 | ' Called when the instance is about to be destroyed. This ' |
| 7682 | 'is also\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7683 | ' called a finalizer or (improperly) a destructor. If a ' |
| 7684 | 'base class\n' |
| 7685 | ' has a "__del__()" method, the derived class\'s ' |
| 7686 | '"__del__()" method,\n' |
| 7687 | ' if any, must explicitly call it to ensure proper deletion ' |
| 7688 | 'of the\n' |
| 7689 | ' base class part of the instance.\n' |
| 7690 | '\n' |
| 7691 | ' It is possible (though not recommended!) for the ' |
| 7692 | '"__del__()" method\n' |
| 7693 | ' to postpone destruction of the instance by creating a new ' |
| 7694 | 'reference\n' |
| 7695 | ' to it. This is called object *resurrection*. It is\n' |
| 7696 | ' implementation-dependent whether "__del__()" is called a ' |
| 7697 | 'second\n' |
| 7698 | ' time when a resurrected object is about to be destroyed; ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7699 | 'the\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7700 | ' current *CPython* implementation only calls it once.\n' |
| 7701 | '\n' |
| 7702 | ' It is not guaranteed that "__del__()" methods are called ' |
| 7703 | 'for\n' |
| 7704 | ' objects that still exist when the interpreter exits.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7705 | '\n' |
| 7706 | ' Note: "del x" doesn\'t directly call "x.__del__()" --- ' |
| 7707 | 'the former\n' |
| 7708 | ' decrements the reference count for "x" by one, and the ' |
| 7709 | 'latter is\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7710 | ' only called when "x"\'s reference count reaches zero.\n' |
| 7711 | '\n' |
| 7712 | ' **CPython implementation detail:** It is possible for a ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7713 | 'reference\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7714 | ' cycle to prevent the reference count of an object from ' |
| 7715 | 'going to\n' |
| 7716 | ' zero. In this case, the cycle will be later detected and ' |
| 7717 | 'deleted\n' |
| 7718 | ' by the *cyclic garbage collector*. A common cause of ' |
| 7719 | 'reference\n' |
| 7720 | ' cycles is when an exception has been caught in a local ' |
| 7721 | 'variable.\n' |
| 7722 | " The frame's locals then reference the exception, which " |
| 7723 | 'references\n' |
| 7724 | ' its own traceback, which references the locals of all ' |
| 7725 | 'frames caught\n' |
| 7726 | ' in the traceback.\n' |
| 7727 | '\n' |
| 7728 | ' See also: Documentation for the "gc" module.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7729 | '\n' |
| 7730 | ' Warning: Due to the precarious circumstances under which\n' |
| 7731 | ' "__del__()" methods are invoked, exceptions that occur ' |
| 7732 | 'during\n' |
| 7733 | ' their execution are ignored, and a warning is printed ' |
| 7734 | 'to\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7735 | ' "sys.stderr" instead. In particular:\n' |
| 7736 | '\n' |
| 7737 | ' * "__del__()" can be invoked when arbitrary code is ' |
| 7738 | 'being\n' |
| 7739 | ' executed, including from any arbitrary thread. If ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7740 | '"__del__()"\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 7741 | ' needs to take a lock or invoke any other blocking ' |
| 7742 | 'resource, it\n' |
| 7743 | ' may deadlock as the resource may already be taken by ' |
| 7744 | 'the code\n' |
| 7745 | ' that gets interrupted to execute "__del__()".\n' |
| 7746 | '\n' |
| 7747 | ' * "__del__()" can be executed during interpreter ' |
| 7748 | 'shutdown. As\n' |
| 7749 | ' a consequence, the global variables it needs to ' |
| 7750 | 'access\n' |
| 7751 | ' (including other modules) may already have been ' |
| 7752 | 'deleted or set\n' |
| 7753 | ' to "None". Python guarantees that globals whose name ' |
| 7754 | 'begins\n' |
| 7755 | ' with a single underscore are deleted from their ' |
| 7756 | 'module before\n' |
| 7757 | ' other globals are deleted; if no other references to ' |
| 7758 | 'such\n' |
| 7759 | ' globals exist, this may help in assuring that ' |
| 7760 | 'imported modules\n' |
| 7761 | ' are still available at the time when the "__del__()" ' |
| 7762 | 'method is\n' |
| 7763 | ' called.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7764 | '\n' |
| 7765 | 'object.__repr__(self)\n' |
| 7766 | '\n' |
| 7767 | ' Called by the "repr()" built-in function to compute the ' |
| 7768 | '"official"\n' |
| 7769 | ' string representation of an object. If at all possible, ' |
| 7770 | 'this\n' |
| 7771 | ' should look like a valid Python expression that could be ' |
| 7772 | 'used to\n' |
| 7773 | ' recreate an object with the same value (given an ' |
| 7774 | 'appropriate\n' |
| 7775 | ' environment). If this is not possible, a string of the ' |
| 7776 | 'form\n' |
| 7777 | ' "<...some useful description...>" should be returned. The ' |
| 7778 | 'return\n' |
| 7779 | ' value must be a string object. If a class defines ' |
| 7780 | '"__repr__()" but\n' |
| 7781 | ' not "__str__()", then "__repr__()" is also used when an ' |
| 7782 | '"informal"\n' |
| 7783 | ' string representation of instances of that class is ' |
| 7784 | 'required.\n' |
| 7785 | '\n' |
| 7786 | ' This is typically used for debugging, so it is important ' |
| 7787 | 'that the\n' |
| 7788 | ' representation is information-rich and unambiguous.\n' |
| 7789 | '\n' |
| 7790 | 'object.__str__(self)\n' |
| 7791 | '\n' |
| 7792 | ' Called by "str(object)" and the built-in functions ' |
| 7793 | '"format()" and\n' |
| 7794 | ' "print()" to compute the "informal" or nicely printable ' |
| 7795 | 'string\n' |
| 7796 | ' representation of an object. The return value must be a ' |
| 7797 | 'string\n' |
| 7798 | ' object.\n' |
| 7799 | '\n' |
| 7800 | ' This method differs from "object.__repr__()" in that ' |
| 7801 | 'there is no\n' |
| 7802 | ' expectation that "__str__()" return a valid Python ' |
| 7803 | 'expression: a\n' |
| 7804 | ' more convenient or concise representation can be used.\n' |
| 7805 | '\n' |
| 7806 | ' The default implementation defined by the built-in type ' |
| 7807 | '"object"\n' |
| 7808 | ' calls "object.__repr__()".\n' |
| 7809 | '\n' |
| 7810 | 'object.__bytes__(self)\n' |
| 7811 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7812 | ' Called by bytes to compute a byte-string representation ' |
| 7813 | 'of an\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7814 | ' object. This should return a "bytes" object.\n' |
| 7815 | '\n' |
| 7816 | 'object.__format__(self, format_spec)\n' |
| 7817 | '\n' |
| 7818 | ' Called by the "format()" built-in function, and by ' |
| 7819 | 'extension,\n' |
| 7820 | ' evaluation of formatted string literals and the ' |
| 7821 | '"str.format()"\n' |
| 7822 | ' method, to produce a "formatted" string representation of ' |
| 7823 | 'an\n' |
| 7824 | ' object. The "format_spec" argument is a string that ' |
| 7825 | 'contains a\n' |
| 7826 | ' description of the formatting options desired. The ' |
| 7827 | 'interpretation\n' |
| 7828 | ' of the "format_spec" argument is up to the type ' |
| 7829 | 'implementing\n' |
| 7830 | ' "__format__()", however most classes will either ' |
| 7831 | 'delegate\n' |
| 7832 | ' formatting to one of the built-in types, or use a ' |
| 7833 | 'similar\n' |
| 7834 | ' formatting option syntax.\n' |
| 7835 | '\n' |
| 7836 | ' See Format Specification Mini-Language for a description ' |
| 7837 | 'of the\n' |
| 7838 | ' standard formatting syntax.\n' |
| 7839 | '\n' |
| 7840 | ' The return value must be a string object.\n' |
| 7841 | '\n' |
| 7842 | ' Changed in version 3.4: The __format__ method of "object" ' |
| 7843 | 'itself\n' |
| 7844 | ' raises a "TypeError" if passed any non-empty string.\n' |
| 7845 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7846 | ' Changed in version 3.7: "object.__format__(x, \'\')" is ' |
| 7847 | 'now\n' |
| 7848 | ' equivalent to "str(x)" rather than "format(str(self), ' |
| 7849 | '\'\')".\n' |
| 7850 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7851 | 'object.__lt__(self, other)\n' |
| 7852 | 'object.__le__(self, other)\n' |
| 7853 | 'object.__eq__(self, other)\n' |
| 7854 | 'object.__ne__(self, other)\n' |
| 7855 | 'object.__gt__(self, other)\n' |
| 7856 | 'object.__ge__(self, other)\n' |
| 7857 | '\n' |
| 7858 | ' These are the so-called "rich comparison" methods. The\n' |
| 7859 | ' correspondence between operator symbols and method names ' |
| 7860 | 'is as\n' |
| 7861 | ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' |
| 7862 | '"x.__le__(y)",\n' |
| 7863 | ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' |
| 7864 | '"x>y" calls\n' |
| 7865 | ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' |
| 7866 | '\n' |
| 7867 | ' A rich comparison method may return the singleton ' |
| 7868 | '"NotImplemented"\n' |
| 7869 | ' if it does not implement the operation for a given pair ' |
| 7870 | 'of\n' |
| 7871 | ' arguments. By convention, "False" and "True" are returned ' |
| 7872 | 'for a\n' |
| 7873 | ' successful comparison. However, these methods can return ' |
| 7874 | 'any value,\n' |
| 7875 | ' so if the comparison operator is used in a Boolean ' |
| 7876 | 'context (e.g.,\n' |
| 7877 | ' in the condition of an "if" statement), Python will call ' |
| 7878 | '"bool()"\n' |
| 7879 | ' on the value to determine if the result is true or ' |
| 7880 | 'false.\n' |
| 7881 | '\n' |
| 7882 | ' By default, "__ne__()" delegates to "__eq__()" and ' |
| 7883 | 'inverts the\n' |
| 7884 | ' result unless it is "NotImplemented". There are no other ' |
| 7885 | 'implied\n' |
| 7886 | ' relationships among the comparison operators, for ' |
| 7887 | 'example, the\n' |
| 7888 | ' truth of "(x<y or x==y)" does not imply "x<=y". To ' |
| 7889 | 'automatically\n' |
| 7890 | ' generate ordering operations from a single root ' |
| 7891 | 'operation, see\n' |
| 7892 | ' "functools.total_ordering()".\n' |
| 7893 | '\n' |
| 7894 | ' See the paragraph on "__hash__()" for some important ' |
| 7895 | 'notes on\n' |
| 7896 | ' creating *hashable* objects which support custom ' |
| 7897 | 'comparison\n' |
| 7898 | ' operations and are usable as dictionary keys.\n' |
| 7899 | '\n' |
| 7900 | ' There are no swapped-argument versions of these methods ' |
| 7901 | '(to be used\n' |
| 7902 | ' when the left argument does not support the operation but ' |
| 7903 | 'the right\n' |
| 7904 | ' argument does); rather, "__lt__()" and "__gt__()" are ' |
| 7905 | "each other's\n" |
| 7906 | ' reflection, "__le__()" and "__ge__()" are each other\'s ' |
| 7907 | 'reflection,\n' |
| 7908 | ' and "__eq__()" and "__ne__()" are their own reflection. ' |
| 7909 | 'If the\n' |
| 7910 | " operands are of different types, and right operand's type " |
| 7911 | 'is a\n' |
| 7912 | " direct or indirect subclass of the left operand's type, " |
| 7913 | 'the\n' |
| 7914 | ' reflected method of the right operand has priority, ' |
| 7915 | 'otherwise the\n' |
| 7916 | " left operand's method has priority. Virtual subclassing " |
| 7917 | 'is not\n' |
| 7918 | ' considered.\n' |
| 7919 | '\n' |
| 7920 | 'object.__hash__(self)\n' |
| 7921 | '\n' |
| 7922 | ' Called by built-in function "hash()" and for operations ' |
| 7923 | 'on members\n' |
| 7924 | ' of hashed collections including "set", "frozenset", and ' |
| 7925 | '"dict".\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7926 | ' "__hash__()" should return an integer. The only required ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7927 | 'property\n' |
| 7928 | ' is that objects which compare equal have the same hash ' |
| 7929 | 'value; it is\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7930 | ' advised to mix together the hash values of the components ' |
| 7931 | 'of the\n' |
| 7932 | ' object that also play a part in comparison of objects by ' |
| 7933 | 'packing\n' |
| 7934 | ' them into a tuple and hashing the tuple. Example:\n' |
| 7935 | '\n' |
| 7936 | ' def __hash__(self):\n' |
| 7937 | ' return hash((self.name, self.nick, self.color))\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7938 | '\n' |
| 7939 | ' Note: "hash()" truncates the value returned from an ' |
| 7940 | "object's\n" |
| 7941 | ' custom "__hash__()" method to the size of a ' |
| 7942 | '"Py_ssize_t". This\n' |
| 7943 | ' is typically 8 bytes on 64-bit builds and 4 bytes on ' |
| 7944 | '32-bit\n' |
| 7945 | ' builds. If an object\'s "__hash__()" must ' |
| 7946 | 'interoperate on builds\n' |
| 7947 | ' of different bit sizes, be sure to check the width on ' |
| 7948 | 'all\n' |
| 7949 | ' supported builds. An easy way to do this is with ' |
| 7950 | '"python -c\n' |
| 7951 | ' "import sys; print(sys.hash_info.width)"".\n' |
| 7952 | '\n' |
| 7953 | ' If a class does not define an "__eq__()" method it should ' |
| 7954 | 'not\n' |
| 7955 | ' define a "__hash__()" operation either; if it defines ' |
| 7956 | '"__eq__()"\n' |
| 7957 | ' but not "__hash__()", its instances will not be usable as ' |
| 7958 | 'items in\n' |
| 7959 | ' hashable collections. If a class defines mutable objects ' |
| 7960 | 'and\n' |
| 7961 | ' implements an "__eq__()" method, it should not implement\n' |
| 7962 | ' "__hash__()", since the implementation of hashable ' |
| 7963 | 'collections\n' |
| 7964 | " requires that a key's hash value is immutable (if the " |
| 7965 | "object's hash\n" |
| 7966 | ' value changes, it will be in the wrong hash bucket).\n' |
| 7967 | '\n' |
| 7968 | ' User-defined classes have "__eq__()" and "__hash__()" ' |
| 7969 | 'methods by\n' |
| 7970 | ' default; with them, all objects compare unequal (except ' |
| 7971 | 'with\n' |
| 7972 | ' themselves) and "x.__hash__()" returns an appropriate ' |
| 7973 | 'value such\n' |
| 7974 | ' that "x == y" implies both that "x is y" and "hash(x) == ' |
| 7975 | 'hash(y)".\n' |
| 7976 | '\n' |
| 7977 | ' A class that overrides "__eq__()" and does not define ' |
| 7978 | '"__hash__()"\n' |
| 7979 | ' will have its "__hash__()" implicitly set to "None". ' |
| 7980 | 'When the\n' |
| 7981 | ' "__hash__()" method of a class is "None", instances of ' |
| 7982 | 'the class\n' |
| 7983 | ' will raise an appropriate "TypeError" when a program ' |
| 7984 | 'attempts to\n' |
| 7985 | ' retrieve their hash value, and will also be correctly ' |
| 7986 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 7987 | ' unhashable when checking "isinstance(obj,\n' |
| 7988 | ' collections.abc.Hashable)".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 7989 | '\n' |
| 7990 | ' If a class that overrides "__eq__()" needs to retain the\n' |
| 7991 | ' implementation of "__hash__()" from a parent class, the ' |
| 7992 | 'interpreter\n' |
| 7993 | ' must be told this explicitly by setting "__hash__ =\n' |
| 7994 | ' <ParentClass>.__hash__".\n' |
| 7995 | '\n' |
| 7996 | ' If a class that does not override "__eq__()" wishes to ' |
| 7997 | 'suppress\n' |
| 7998 | ' hash support, it should include "__hash__ = None" in the ' |
| 7999 | 'class\n' |
| 8000 | ' definition. A class which defines its own "__hash__()" ' |
| 8001 | 'that\n' |
| 8002 | ' explicitly raises a "TypeError" would be incorrectly ' |
| 8003 | 'identified as\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8004 | ' hashable by an "isinstance(obj, ' |
| 8005 | 'collections.abc.Hashable)" call.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8006 | '\n' |
| 8007 | ' Note: By default, the "__hash__()" values of str, bytes ' |
| 8008 | 'and\n' |
| 8009 | ' datetime objects are "salted" with an unpredictable ' |
| 8010 | 'random value.\n' |
| 8011 | ' Although they remain constant within an individual ' |
| 8012 | 'Python\n' |
| 8013 | ' process, they are not predictable between repeated ' |
| 8014 | 'invocations of\n' |
| 8015 | ' Python.This is intended to provide protection against a ' |
| 8016 | 'denial-\n' |
| 8017 | ' of-service caused by carefully-chosen inputs that ' |
| 8018 | 'exploit the\n' |
| 8019 | ' worst case performance of a dict insertion, O(n^2) ' |
| 8020 | 'complexity.\n' |
| 8021 | ' See http://www.ocert.org/advisories/ocert-2011-003.html ' |
| 8022 | 'for\n' |
| 8023 | ' details.Changing hash values affects the iteration ' |
| 8024 | 'order of\n' |
| 8025 | ' dicts, sets and other mappings. Python has never made ' |
| 8026 | 'guarantees\n' |
| 8027 | ' about this ordering (and it typically varies between ' |
| 8028 | '32-bit and\n' |
| 8029 | ' 64-bit builds).See also "PYTHONHASHSEED".\n' |
| 8030 | '\n' |
| 8031 | ' Changed in version 3.3: Hash randomization is enabled by ' |
| 8032 | 'default.\n' |
| 8033 | '\n' |
| 8034 | 'object.__bool__(self)\n' |
| 8035 | '\n' |
| 8036 | ' Called to implement truth value testing and the built-in ' |
| 8037 | 'operation\n' |
| 8038 | ' "bool()"; should return "False" or "True". When this ' |
| 8039 | 'method is not\n' |
| 8040 | ' defined, "__len__()" is called, if it is defined, and the ' |
| 8041 | 'object is\n' |
| 8042 | ' considered true if its result is nonzero. If a class ' |
| 8043 | 'defines\n' |
| 8044 | ' neither "__len__()" nor "__bool__()", all its instances ' |
| 8045 | 'are\n' |
| 8046 | ' considered true.\n' |
| 8047 | '\n' |
| 8048 | '\n' |
| 8049 | 'Customizing attribute access\n' |
| 8050 | '============================\n' |
| 8051 | '\n' |
| 8052 | 'The following methods can be defined to customize the ' |
| 8053 | 'meaning of\n' |
| 8054 | 'attribute access (use of, assignment to, or deletion of ' |
| 8055 | '"x.name") for\n' |
| 8056 | 'class instances.\n' |
| 8057 | '\n' |
| 8058 | 'object.__getattr__(self, name)\n' |
| 8059 | '\n' |
| 8060 | ' Called when an attribute lookup has not found the ' |
| 8061 | 'attribute in the\n' |
| 8062 | ' usual places (i.e. it is not an instance attribute nor is ' |
| 8063 | 'it found\n' |
| 8064 | ' in the class tree for "self"). "name" is the attribute ' |
| 8065 | 'name. This\n' |
| 8066 | ' method should return the (computed) attribute value or ' |
| 8067 | 'raise an\n' |
| 8068 | ' "AttributeError" exception.\n' |
| 8069 | '\n' |
| 8070 | ' Note that if the attribute is found through the normal ' |
| 8071 | 'mechanism,\n' |
| 8072 | ' "__getattr__()" is not called. (This is an intentional ' |
| 8073 | 'asymmetry\n' |
| 8074 | ' between "__getattr__()" and "__setattr__()".) This is ' |
| 8075 | 'done both for\n' |
| 8076 | ' efficiency reasons and because otherwise "__getattr__()" ' |
| 8077 | 'would have\n' |
| 8078 | ' no way to access other attributes of the instance. Note ' |
| 8079 | 'that at\n' |
| 8080 | ' least for instance variables, you can fake total control ' |
| 8081 | 'by not\n' |
| 8082 | ' inserting any values in the instance attribute dictionary ' |
| 8083 | '(but\n' |
| 8084 | ' instead inserting them in another object). See the\n' |
| 8085 | ' "__getattribute__()" method below for a way to actually ' |
| 8086 | 'get total\n' |
| 8087 | ' control over attribute access.\n' |
| 8088 | '\n' |
| 8089 | 'object.__getattribute__(self, name)\n' |
| 8090 | '\n' |
| 8091 | ' Called unconditionally to implement attribute accesses ' |
| 8092 | 'for\n' |
| 8093 | ' instances of the class. If the class also defines ' |
| 8094 | '"__getattr__()",\n' |
| 8095 | ' the latter will not be called unless "__getattribute__()" ' |
| 8096 | 'either\n' |
| 8097 | ' calls it explicitly or raises an "AttributeError". This ' |
| 8098 | 'method\n' |
| 8099 | ' should return the (computed) attribute value or raise an\n' |
| 8100 | ' "AttributeError" exception. In order to avoid infinite ' |
| 8101 | 'recursion in\n' |
| 8102 | ' this method, its implementation should always call the ' |
| 8103 | 'base class\n' |
| 8104 | ' method with the same name to access any attributes it ' |
| 8105 | 'needs, for\n' |
| 8106 | ' example, "object.__getattribute__(self, name)".\n' |
| 8107 | '\n' |
| 8108 | ' Note: This method may still be bypassed when looking up ' |
| 8109 | 'special\n' |
| 8110 | ' methods as the result of implicit invocation via ' |
| 8111 | 'language syntax\n' |
| 8112 | ' or built-in functions. See Special method lookup.\n' |
| 8113 | '\n' |
| 8114 | 'object.__setattr__(self, name, value)\n' |
| 8115 | '\n' |
| 8116 | ' Called when an attribute assignment is attempted. This ' |
| 8117 | 'is called\n' |
| 8118 | ' instead of the normal mechanism (i.e. store the value in ' |
| 8119 | 'the\n' |
| 8120 | ' instance dictionary). *name* is the attribute name, ' |
| 8121 | '*value* is the\n' |
| 8122 | ' value to be assigned to it.\n' |
| 8123 | '\n' |
| 8124 | ' If "__setattr__()" wants to assign to an instance ' |
| 8125 | 'attribute, it\n' |
| 8126 | ' should call the base class method with the same name, for ' |
| 8127 | 'example,\n' |
| 8128 | ' "object.__setattr__(self, name, value)".\n' |
| 8129 | '\n' |
| 8130 | 'object.__delattr__(self, name)\n' |
| 8131 | '\n' |
| 8132 | ' Like "__setattr__()" but for attribute deletion instead ' |
| 8133 | 'of\n' |
| 8134 | ' assignment. This should only be implemented if "del ' |
| 8135 | 'obj.name" is\n' |
| 8136 | ' meaningful for the object.\n' |
| 8137 | '\n' |
| 8138 | 'object.__dir__(self)\n' |
| 8139 | '\n' |
| 8140 | ' Called when "dir()" is called on the object. A sequence ' |
| 8141 | 'must be\n' |
| 8142 | ' returned. "dir()" converts the returned sequence to a ' |
| 8143 | 'list and\n' |
| 8144 | ' sorts it.\n' |
| 8145 | '\n' |
| 8146 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 8147 | 'Customizing module attribute access\n' |
| 8148 | '-----------------------------------\n' |
| 8149 | '\n' |
| 8150 | 'Special names "__getattr__" and "__dir__" can be also used ' |
| 8151 | 'to\n' |
| 8152 | 'customize access to module attributes. The "__getattr__" ' |
| 8153 | 'function at\n' |
| 8154 | 'the module level should accept one argument which is the ' |
| 8155 | 'name of an\n' |
| 8156 | 'attribute and return the computed value or raise an ' |
| 8157 | '"AttributeError".\n' |
| 8158 | 'If an attribute is not found on a module object through the ' |
| 8159 | 'normal\n' |
| 8160 | 'lookup, i.e. "object.__getattribute__()", then "__getattr__" ' |
| 8161 | 'is\n' |
| 8162 | 'searched in the module "__dict__" before raising an ' |
| 8163 | '"AttributeError".\n' |
| 8164 | 'If found, it is called with the attribute name and the ' |
| 8165 | 'result is\n' |
| 8166 | 'returned.\n' |
| 8167 | '\n' |
| 8168 | 'The "__dir__" function should accept no arguments, and ' |
| 8169 | 'return a list\n' |
| 8170 | 'of strings that represents the names accessible on module. ' |
| 8171 | 'If present,\n' |
| 8172 | 'this function overrides the standard "dir()" search on a ' |
| 8173 | 'module.\n' |
| 8174 | '\n' |
| 8175 | 'For a more fine grained customization of the module behavior ' |
| 8176 | '(setting\n' |
| 8177 | 'attributes, properties, etc.), one can set the "__class__" ' |
| 8178 | 'attribute\n' |
| 8179 | 'of a module object to a subclass of "types.ModuleType". For ' |
| 8180 | 'example:\n' |
| 8181 | '\n' |
| 8182 | ' import sys\n' |
| 8183 | ' from types import ModuleType\n' |
| 8184 | '\n' |
| 8185 | ' class VerboseModule(ModuleType):\n' |
| 8186 | ' def __repr__(self):\n' |
| 8187 | " return f'Verbose {self.__name__}'\n" |
| 8188 | '\n' |
| 8189 | ' def __setattr__(self, attr, value):\n' |
| 8190 | " print(f'Setting {attr}...')\n" |
| 8191 | ' setattr(self, attr, value)\n' |
| 8192 | '\n' |
| 8193 | ' sys.modules[__name__].__class__ = VerboseModule\n' |
| 8194 | '\n' |
| 8195 | 'Note: Defining module "__getattr__" and setting module ' |
| 8196 | '"__class__"\n' |
| 8197 | ' only affect lookups made using the attribute access syntax ' |
| 8198 | '--\n' |
| 8199 | ' directly accessing the module globals (whether by code ' |
| 8200 | 'within the\n' |
| 8201 | " module, or via a reference to the module's globals " |
| 8202 | 'dictionary) is\n' |
| 8203 | ' unaffected.\n' |
| 8204 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 8205 | 'Changed in version 3.5: "__class__" module attribute is now ' |
| 8206 | 'writable.\n' |
| 8207 | '\n' |
| 8208 | 'New in version 3.7: "__getattr__" and "__dir__" module ' |
| 8209 | 'attributes.\n' |
| 8210 | '\n' |
| 8211 | 'See also:\n' |
| 8212 | '\n' |
| 8213 | ' **PEP 562** - Module __getattr__ and __dir__\n' |
| 8214 | ' Describes the "__getattr__" and "__dir__" functions on ' |
| 8215 | 'modules.\n' |
| 8216 | '\n' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 8217 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8218 | 'Implementing Descriptors\n' |
| 8219 | '------------------------\n' |
| 8220 | '\n' |
| 8221 | 'The following methods only apply when an instance of the ' |
| 8222 | 'class\n' |
| 8223 | 'containing the method (a so-called *descriptor* class) ' |
| 8224 | 'appears in an\n' |
| 8225 | "*owner* class (the descriptor must be in either the owner's " |
| 8226 | 'class\n' |
| 8227 | 'dictionary or in the class dictionary for one of its ' |
| 8228 | 'parents). In the\n' |
| 8229 | 'examples below, "the attribute" refers to the attribute ' |
| 8230 | 'whose name is\n' |
| 8231 | 'the key of the property in the owner class\' "__dict__".\n' |
| 8232 | '\n' |
| 8233 | 'object.__get__(self, instance, owner)\n' |
| 8234 | '\n' |
| 8235 | ' Called to get the attribute of the owner class (class ' |
| 8236 | 'attribute\n' |
| 8237 | ' access) or of an instance of that class (instance ' |
| 8238 | 'attribute\n' |
| 8239 | ' access). *owner* is always the owner class, while ' |
| 8240 | '*instance* is the\n' |
| 8241 | ' instance that the attribute was accessed through, or ' |
| 8242 | '"None" when\n' |
| 8243 | ' the attribute is accessed through the *owner*. This ' |
| 8244 | 'method should\n' |
| 8245 | ' return the (computed) attribute value or raise an ' |
| 8246 | '"AttributeError"\n' |
| 8247 | ' exception.\n' |
| 8248 | '\n' |
| 8249 | 'object.__set__(self, instance, value)\n' |
| 8250 | '\n' |
| 8251 | ' Called to set the attribute on an instance *instance* of ' |
| 8252 | 'the owner\n' |
| 8253 | ' class to a new value, *value*.\n' |
| 8254 | '\n' |
| 8255 | 'object.__delete__(self, instance)\n' |
| 8256 | '\n' |
| 8257 | ' Called to delete the attribute on an instance *instance* ' |
| 8258 | 'of the\n' |
| 8259 | ' owner class.\n' |
| 8260 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 8261 | 'object.__set_name__(self, owner, name)\n' |
| 8262 | '\n' |
| 8263 | ' Called at the time the owning class *owner* is created. ' |
| 8264 | 'The\n' |
| 8265 | ' descriptor has been assigned to *name*.\n' |
| 8266 | '\n' |
| 8267 | ' New in version 3.6.\n' |
| 8268 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8269 | 'The attribute "__objclass__" is interpreted by the "inspect" ' |
| 8270 | 'module as\n' |
| 8271 | 'specifying the class where this object was defined (setting ' |
| 8272 | 'this\n' |
| 8273 | 'appropriately can assist in runtime introspection of dynamic ' |
| 8274 | 'class\n' |
| 8275 | 'attributes). For callables, it may indicate that an instance ' |
| 8276 | 'of the\n' |
| 8277 | 'given type (or a subclass) is expected or required as the ' |
| 8278 | 'first\n' |
| 8279 | 'positional argument (for example, CPython sets this ' |
| 8280 | 'attribute for\n' |
| 8281 | 'unbound methods that are implemented in C).\n' |
| 8282 | '\n' |
| 8283 | '\n' |
| 8284 | 'Invoking Descriptors\n' |
| 8285 | '--------------------\n' |
| 8286 | '\n' |
| 8287 | 'In general, a descriptor is an object attribute with ' |
| 8288 | '"binding\n' |
| 8289 | 'behavior", one whose attribute access has been overridden by ' |
| 8290 | 'methods\n' |
| 8291 | 'in the descriptor protocol: "__get__()", "__set__()", and\n' |
| 8292 | '"__delete__()". If any of those methods are defined for an ' |
| 8293 | 'object, it\n' |
| 8294 | 'is said to be a descriptor.\n' |
| 8295 | '\n' |
| 8296 | 'The default behavior for attribute access is to get, set, or ' |
| 8297 | 'delete\n' |
| 8298 | "the attribute from an object's dictionary. For instance, " |
| 8299 | '"a.x" has a\n' |
| 8300 | 'lookup chain starting with "a.__dict__[\'x\']", then\n' |
| 8301 | '"type(a).__dict__[\'x\']", and continuing through the base ' |
| 8302 | 'classes of\n' |
| 8303 | '"type(a)" excluding metaclasses.\n' |
| 8304 | '\n' |
| 8305 | 'However, if the looked-up value is an object defining one of ' |
| 8306 | 'the\n' |
| 8307 | 'descriptor methods, then Python may override the default ' |
| 8308 | 'behavior and\n' |
| 8309 | 'invoke the descriptor method instead. Where this occurs in ' |
| 8310 | 'the\n' |
| 8311 | 'precedence chain depends on which descriptor methods were ' |
| 8312 | 'defined and\n' |
| 8313 | 'how they were called.\n' |
| 8314 | '\n' |
| 8315 | 'The starting point for descriptor invocation is a binding, ' |
| 8316 | '"a.x". How\n' |
| 8317 | 'the arguments are assembled depends on "a":\n' |
| 8318 | '\n' |
| 8319 | 'Direct Call\n' |
| 8320 | ' The simplest and least common call is when user code ' |
| 8321 | 'directly\n' |
| 8322 | ' invokes a descriptor method: "x.__get__(a)".\n' |
| 8323 | '\n' |
| 8324 | 'Instance Binding\n' |
| 8325 | ' If binding to an object instance, "a.x" is transformed ' |
| 8326 | 'into the\n' |
| 8327 | ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' |
| 8328 | '\n' |
| 8329 | 'Class Binding\n' |
| 8330 | ' If binding to a class, "A.x" is transformed into the ' |
| 8331 | 'call:\n' |
| 8332 | ' "A.__dict__[\'x\'].__get__(None, A)".\n' |
| 8333 | '\n' |
| 8334 | 'Super Binding\n' |
| 8335 | ' If "a" is an instance of "super", then the binding ' |
| 8336 | '"super(B,\n' |
| 8337 | ' obj).m()" searches "obj.__class__.__mro__" for the base ' |
| 8338 | 'class "A"\n' |
| 8339 | ' immediately preceding "B" and then invokes the descriptor ' |
| 8340 | 'with the\n' |
| 8341 | ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n' |
| 8342 | '\n' |
| 8343 | 'For instance bindings, the precedence of descriptor ' |
| 8344 | 'invocation depends\n' |
| 8345 | 'on the which descriptor methods are defined. A descriptor ' |
| 8346 | 'can define\n' |
| 8347 | 'any combination of "__get__()", "__set__()" and ' |
| 8348 | '"__delete__()". If it\n' |
| 8349 | 'does not define "__get__()", then accessing the attribute ' |
| 8350 | 'will return\n' |
| 8351 | 'the descriptor object itself unless there is a value in the ' |
| 8352 | "object's\n" |
| 8353 | 'instance dictionary. If the descriptor defines "__set__()" ' |
| 8354 | 'and/or\n' |
| 8355 | '"__delete__()", it is a data descriptor; if it defines ' |
| 8356 | 'neither, it is\n' |
| 8357 | 'a non-data descriptor. Normally, data descriptors define ' |
| 8358 | 'both\n' |
| 8359 | '"__get__()" and "__set__()", while non-data descriptors have ' |
| 8360 | 'just the\n' |
| 8361 | '"__get__()" method. Data descriptors with "__set__()" and ' |
| 8362 | '"__get__()"\n' |
| 8363 | 'defined always override a redefinition in an instance ' |
| 8364 | 'dictionary. In\n' |
| 8365 | 'contrast, non-data descriptors can be overridden by ' |
| 8366 | 'instances.\n' |
| 8367 | '\n' |
| 8368 | 'Python methods (including "staticmethod()" and ' |
| 8369 | '"classmethod()") are\n' |
| 8370 | 'implemented as non-data descriptors. Accordingly, instances ' |
| 8371 | 'can\n' |
| 8372 | 'redefine and override methods. This allows individual ' |
| 8373 | 'instances to\n' |
| 8374 | 'acquire behaviors that differ from other instances of the ' |
| 8375 | 'same class.\n' |
| 8376 | '\n' |
| 8377 | 'The "property()" function is implemented as a data ' |
| 8378 | 'descriptor.\n' |
| 8379 | 'Accordingly, instances cannot override the behavior of a ' |
| 8380 | 'property.\n' |
| 8381 | '\n' |
| 8382 | '\n' |
| 8383 | '__slots__\n' |
| 8384 | '---------\n' |
| 8385 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8386 | '*__slots__* allow us to explicitly declare data members ' |
| 8387 | '(like\n' |
| 8388 | 'properties) and deny the creation of *__dict__* and ' |
| 8389 | '*__weakref__*\n' |
| 8390 | '(unless explicitly declared in *__slots__* or available in a ' |
| 8391 | 'parent.)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8392 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8393 | 'The space saved over using *__dict__* can be significant.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8394 | '\n' |
| 8395 | 'object.__slots__\n' |
| 8396 | '\n' |
| 8397 | ' This class variable can be assigned a string, iterable, ' |
| 8398 | 'or sequence\n' |
| 8399 | ' of strings with variable names used by instances. ' |
| 8400 | '*__slots__*\n' |
| 8401 | ' reserves space for the declared variables and prevents ' |
| 8402 | 'the\n' |
| 8403 | ' automatic creation of *__dict__* and *__weakref__* for ' |
| 8404 | 'each\n' |
| 8405 | ' instance.\n' |
| 8406 | '\n' |
| 8407 | '\n' |
| 8408 | 'Notes on using *__slots__*\n' |
| 8409 | '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' |
| 8410 | '\n' |
| 8411 | '* When inheriting from a class without *__slots__*, the ' |
| 8412 | '*__dict__*\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8413 | ' and *__weakref__* attribute of the instances will always ' |
| 8414 | 'be\n' |
| 8415 | ' accessible.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8416 | '\n' |
| 8417 | '* Without a *__dict__* variable, instances cannot be ' |
| 8418 | 'assigned new\n' |
| 8419 | ' variables not listed in the *__slots__* definition. ' |
| 8420 | 'Attempts to\n' |
| 8421 | ' assign to an unlisted variable name raises ' |
| 8422 | '"AttributeError". If\n' |
| 8423 | ' dynamic assignment of new variables is desired, then add\n' |
| 8424 | ' "\'__dict__\'" to the sequence of strings in the ' |
| 8425 | '*__slots__*\n' |
| 8426 | ' declaration.\n' |
| 8427 | '\n' |
| 8428 | '* Without a *__weakref__* variable for each instance, ' |
| 8429 | 'classes\n' |
| 8430 | ' defining *__slots__* do not support weak references to ' |
| 8431 | 'its\n' |
| 8432 | ' instances. If weak reference support is needed, then add\n' |
| 8433 | ' "\'__weakref__\'" to the sequence of strings in the ' |
| 8434 | '*__slots__*\n' |
| 8435 | ' declaration.\n' |
| 8436 | '\n' |
| 8437 | '* *__slots__* are implemented at the class level by ' |
| 8438 | 'creating\n' |
| 8439 | ' descriptors (Implementing Descriptors) for each variable ' |
| 8440 | 'name. As a\n' |
| 8441 | ' result, class attributes cannot be used to set default ' |
| 8442 | 'values for\n' |
| 8443 | ' instance variables defined by *__slots__*; otherwise, the ' |
| 8444 | 'class\n' |
| 8445 | ' attribute would overwrite the descriptor assignment.\n' |
| 8446 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8447 | '* The action of a *__slots__* declaration is not limited to ' |
| 8448 | 'the\n' |
| 8449 | ' class where it is defined. *__slots__* declared in ' |
| 8450 | 'parents are\n' |
| 8451 | ' available in child classes. However, child subclasses will ' |
| 8452 | 'get a\n' |
| 8453 | ' *__dict__* and *__weakref__* unless they also define ' |
| 8454 | '*__slots__*\n' |
| 8455 | ' (which should only contain names of any *additional* ' |
| 8456 | 'slots).\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8457 | '\n' |
| 8458 | '* If a class defines a slot also defined in a base class, ' |
| 8459 | 'the\n' |
| 8460 | ' instance variable defined by the base class slot is ' |
| 8461 | 'inaccessible\n' |
| 8462 | ' (except by retrieving its descriptor directly from the ' |
| 8463 | 'base class).\n' |
| 8464 | ' This renders the meaning of the program undefined. In the ' |
| 8465 | 'future, a\n' |
| 8466 | ' check may be added to prevent this.\n' |
| 8467 | '\n' |
| 8468 | '* Nonempty *__slots__* does not work for classes derived ' |
| 8469 | 'from\n' |
| 8470 | ' "variable-length" built-in types such as "int", "bytes" ' |
| 8471 | 'and "tuple".\n' |
| 8472 | '\n' |
| 8473 | '* Any non-string iterable may be assigned to *__slots__*. ' |
| 8474 | 'Mappings\n' |
| 8475 | ' may also be used; however, in the future, special meaning ' |
| 8476 | 'may be\n' |
| 8477 | ' assigned to the values corresponding to each key.\n' |
| 8478 | '\n' |
| 8479 | '* *__class__* assignment works only if both classes have the ' |
| 8480 | 'same\n' |
| 8481 | ' *__slots__*.\n' |
| 8482 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8483 | '* Multiple inheritance with multiple slotted parent classes ' |
| 8484 | 'can be\n' |
| 8485 | ' used, but only one parent is allowed to have attributes ' |
| 8486 | 'created by\n' |
| 8487 | ' slots (the other bases must have empty slot layouts) - ' |
| 8488 | 'violations\n' |
| 8489 | ' raise "TypeError".\n' |
| 8490 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8491 | '\n' |
| 8492 | 'Customizing class creation\n' |
| 8493 | '==========================\n' |
| 8494 | '\n' |
Ned Deily | 46b0a32 | 2016-08-15 16:12:59 -0400 | [diff] [blame] | 8495 | 'Whenever a class inherits from another class, ' |
| 8496 | '*__init_subclass__* is\n' |
| 8497 | 'called on that class. This way, it is possible to write ' |
| 8498 | 'classes which\n' |
| 8499 | 'change the behavior of subclasses. This is closely related ' |
| 8500 | 'to class\n' |
| 8501 | 'decorators, but where class decorators only affect the ' |
| 8502 | 'specific class\n' |
| 8503 | 'they\'re applied to, "__init_subclass__" solely applies to ' |
| 8504 | 'future\n' |
| 8505 | 'subclasses of the class defining the method.\n' |
| 8506 | '\n' |
| 8507 | 'classmethod object.__init_subclass__(cls)\n' |
| 8508 | '\n' |
| 8509 | ' This method is called whenever the containing class is ' |
| 8510 | 'subclassed.\n' |
| 8511 | ' *cls* is then the new subclass. If defined as a normal ' |
| 8512 | 'instance\n' |
| 8513 | ' method, this method is implicitly converted to a class ' |
| 8514 | 'method.\n' |
| 8515 | '\n' |
| 8516 | ' Keyword arguments which are given to a new class are ' |
| 8517 | 'passed to the\n' |
| 8518 | ' parent\'s class "__init_subclass__". For compatibility ' |
| 8519 | 'with other\n' |
| 8520 | ' classes using "__init_subclass__", one should take out ' |
| 8521 | 'the needed\n' |
| 8522 | ' keyword arguments and pass the others over to the base ' |
| 8523 | 'class, as\n' |
| 8524 | ' in:\n' |
| 8525 | '\n' |
| 8526 | ' class Philosopher:\n' |
| 8527 | ' def __init_subclass__(cls, default_name, ' |
| 8528 | '**kwargs):\n' |
| 8529 | ' super().__init_subclass__(**kwargs)\n' |
| 8530 | ' cls.default_name = default_name\n' |
| 8531 | '\n' |
| 8532 | ' class AustralianPhilosopher(Philosopher, ' |
| 8533 | 'default_name="Bruce"):\n' |
| 8534 | ' pass\n' |
| 8535 | '\n' |
| 8536 | ' The default implementation "object.__init_subclass__" ' |
| 8537 | 'does nothing,\n' |
| 8538 | ' but raises an error if it is called with any arguments.\n' |
| 8539 | '\n' |
| 8540 | ' Note: The metaclass hint "metaclass" is consumed by the ' |
| 8541 | 'rest of\n' |
| 8542 | ' the type machinery, and is never passed to ' |
| 8543 | '"__init_subclass__"\n' |
| 8544 | ' implementations. The actual metaclass (rather than the ' |
| 8545 | 'explicit\n' |
| 8546 | ' hint) can be accessed as "type(cls)".\n' |
| 8547 | '\n' |
| 8548 | ' New in version 3.6.\n' |
| 8549 | '\n' |
| 8550 | '\n' |
| 8551 | 'Metaclasses\n' |
| 8552 | '-----------\n' |
| 8553 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8554 | 'By default, classes are constructed using "type()". The ' |
| 8555 | 'class body is\n' |
| 8556 | 'executed in a new namespace and the class name is bound ' |
| 8557 | 'locally to the\n' |
| 8558 | 'result of "type(name, bases, namespace)".\n' |
| 8559 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 8560 | 'The class creation process can be customized by passing the\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8561 | '"metaclass" keyword argument in the class definition line, ' |
| 8562 | 'or by\n' |
| 8563 | 'inheriting from an existing class that included such an ' |
| 8564 | 'argument. In\n' |
| 8565 | 'the following example, both "MyClass" and "MySubclass" are ' |
| 8566 | 'instances\n' |
| 8567 | 'of "Meta":\n' |
| 8568 | '\n' |
| 8569 | ' class Meta(type):\n' |
| 8570 | ' pass\n' |
| 8571 | '\n' |
| 8572 | ' class MyClass(metaclass=Meta):\n' |
| 8573 | ' pass\n' |
| 8574 | '\n' |
| 8575 | ' class MySubclass(MyClass):\n' |
| 8576 | ' pass\n' |
| 8577 | '\n' |
| 8578 | 'Any other keyword arguments that are specified in the class ' |
| 8579 | 'definition\n' |
| 8580 | 'are passed through to all metaclass operations described ' |
| 8581 | 'below.\n' |
| 8582 | '\n' |
| 8583 | 'When a class definition is executed, the following steps ' |
| 8584 | 'occur:\n' |
| 8585 | '\n' |
| 8586 | '* the appropriate metaclass is determined\n' |
| 8587 | '\n' |
| 8588 | '* the class namespace is prepared\n' |
| 8589 | '\n' |
| 8590 | '* the class body is executed\n' |
| 8591 | '\n' |
| 8592 | '* the class object is created\n' |
| 8593 | '\n' |
| 8594 | '\n' |
| 8595 | 'Determining the appropriate metaclass\n' |
| 8596 | '-------------------------------------\n' |
| 8597 | '\n' |
| 8598 | 'The appropriate metaclass for a class definition is ' |
| 8599 | 'determined as\n' |
| 8600 | 'follows:\n' |
| 8601 | '\n' |
| 8602 | '* if no bases and no explicit metaclass are given, then ' |
| 8603 | '"type()" is\n' |
| 8604 | ' used\n' |
| 8605 | '\n' |
| 8606 | '* if an explicit metaclass is given and it is *not* an ' |
| 8607 | 'instance of\n' |
| 8608 | ' "type()", then it is used directly as the metaclass\n' |
| 8609 | '\n' |
| 8610 | '* if an instance of "type()" is given as the explicit ' |
| 8611 | 'metaclass, or\n' |
| 8612 | ' bases are defined, then the most derived metaclass is ' |
| 8613 | 'used\n' |
| 8614 | '\n' |
| 8615 | 'The most derived metaclass is selected from the explicitly ' |
| 8616 | 'specified\n' |
| 8617 | 'metaclass (if any) and the metaclasses (i.e. "type(cls)") of ' |
| 8618 | 'all\n' |
| 8619 | 'specified base classes. The most derived metaclass is one ' |
| 8620 | 'which is a\n' |
| 8621 | 'subtype of *all* of these candidate metaclasses. If none of ' |
| 8622 | 'the\n' |
| 8623 | 'candidate metaclasses meets that criterion, then the class ' |
| 8624 | 'definition\n' |
| 8625 | 'will fail with "TypeError".\n' |
| 8626 | '\n' |
| 8627 | '\n' |
| 8628 | 'Preparing the class namespace\n' |
| 8629 | '-----------------------------\n' |
| 8630 | '\n' |
| 8631 | 'Once the appropriate metaclass has been identified, then the ' |
| 8632 | 'class\n' |
| 8633 | 'namespace is prepared. If the metaclass has a "__prepare__" ' |
| 8634 | 'attribute,\n' |
| 8635 | 'it is called as "namespace = metaclass.__prepare__(name, ' |
| 8636 | 'bases,\n' |
| 8637 | '**kwds)" (where the additional keyword arguments, if any, ' |
| 8638 | 'come from\n' |
| 8639 | 'the class definition).\n' |
| 8640 | '\n' |
| 8641 | 'If the metaclass has no "__prepare__" attribute, then the ' |
| 8642 | 'class\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 8643 | 'namespace is initialised as an empty ordered mapping.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8644 | '\n' |
| 8645 | 'See also:\n' |
| 8646 | '\n' |
| 8647 | ' **PEP 3115** - Metaclasses in Python 3000\n' |
| 8648 | ' Introduced the "__prepare__" namespace hook\n' |
| 8649 | '\n' |
| 8650 | '\n' |
| 8651 | 'Executing the class body\n' |
| 8652 | '------------------------\n' |
| 8653 | '\n' |
| 8654 | 'The class body is executed (approximately) as "exec(body, ' |
| 8655 | 'globals(),\n' |
| 8656 | 'namespace)". The key difference from a normal call to ' |
| 8657 | '"exec()" is that\n' |
| 8658 | 'lexical scoping allows the class body (including any ' |
| 8659 | 'methods) to\n' |
| 8660 | 'reference names from the current and outer scopes when the ' |
| 8661 | 'class\n' |
| 8662 | 'definition occurs inside a function.\n' |
| 8663 | '\n' |
| 8664 | 'However, even when the class definition occurs inside the ' |
| 8665 | 'function,\n' |
| 8666 | 'methods defined inside the class still cannot see names ' |
| 8667 | 'defined at the\n' |
| 8668 | 'class scope. Class variables must be accessed through the ' |
| 8669 | 'first\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8670 | 'parameter of instance or class methods, or through the ' |
| 8671 | 'implicit\n' |
| 8672 | 'lexically scoped "__class__" reference described in the next ' |
| 8673 | 'section.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8674 | '\n' |
| 8675 | '\n' |
| 8676 | 'Creating the class object\n' |
| 8677 | '-------------------------\n' |
| 8678 | '\n' |
| 8679 | 'Once the class namespace has been populated by executing the ' |
| 8680 | 'class\n' |
| 8681 | 'body, the class object is created by calling ' |
| 8682 | '"metaclass(name, bases,\n' |
| 8683 | 'namespace, **kwds)" (the additional keywords passed here are ' |
| 8684 | 'the same\n' |
| 8685 | 'as those passed to "__prepare__").\n' |
| 8686 | '\n' |
| 8687 | 'This class object is the one that will be referenced by the ' |
| 8688 | 'zero-\n' |
| 8689 | 'argument form of "super()". "__class__" is an implicit ' |
| 8690 | 'closure\n' |
| 8691 | 'reference created by the compiler if any methods in a class ' |
| 8692 | 'body refer\n' |
| 8693 | 'to either "__class__" or "super". This allows the zero ' |
| 8694 | 'argument form\n' |
| 8695 | 'of "super()" to correctly identify the class being defined ' |
| 8696 | 'based on\n' |
| 8697 | 'lexical scoping, while the class or instance that was used ' |
| 8698 | 'to make the\n' |
| 8699 | 'current call is identified based on the first argument ' |
| 8700 | 'passed to the\n' |
| 8701 | 'method.\n' |
| 8702 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8703 | '**CPython implementation detail:** In CPython 3.6 and later, ' |
| 8704 | 'the\n' |
| 8705 | '"__class__" cell is passed to the metaclass as a ' |
| 8706 | '"__classcell__" entry\n' |
| 8707 | 'in the class namespace. If present, this must be propagated ' |
| 8708 | 'up to the\n' |
| 8709 | '"type.__new__" call in order for the class to be ' |
| 8710 | 'initialised\n' |
| 8711 | 'correctly. Failing to do so will result in a ' |
| 8712 | '"DeprecationWarning" in\n' |
| 8713 | 'Python 3.6, and a "RuntimeWarning" in the future.\n' |
| 8714 | '\n' |
| 8715 | 'When using the default metaclass "type", or any metaclass ' |
| 8716 | 'that\n' |
| 8717 | 'ultimately calls "type.__new__", the following additional\n' |
| 8718 | 'customisation steps are invoked after creating the class ' |
| 8719 | 'object:\n' |
| 8720 | '\n' |
| 8721 | '* first, "type.__new__" collects all of the descriptors in ' |
| 8722 | 'the class\n' |
| 8723 | ' namespace that define a "__set_name__()" method;\n' |
| 8724 | '\n' |
| 8725 | '* second, all of these "__set_name__" methods are called ' |
| 8726 | 'with the\n' |
| 8727 | ' class being defined and the assigned name of that ' |
| 8728 | 'particular\n' |
| 8729 | ' descriptor; and\n' |
| 8730 | '\n' |
| 8731 | '* finally, the "__init_subclass__()" hook is called on the ' |
| 8732 | 'immediate\n' |
| 8733 | ' parent of the new class in its method resolution order.\n' |
| 8734 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8735 | 'After the class object is created, it is passed to the ' |
| 8736 | 'class\n' |
| 8737 | 'decorators included in the class definition (if any) and the ' |
| 8738 | 'resulting\n' |
| 8739 | 'object is bound in the local namespace as the defined ' |
| 8740 | 'class.\n' |
| 8741 | '\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 8742 | 'When a new class is created by "type.__new__", the object ' |
| 8743 | 'provided as\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 8744 | 'the namespace parameter is copied to a new ordered mapping ' |
| 8745 | 'and the\n' |
| 8746 | 'original object is discarded. The new copy is wrapped in a ' |
| 8747 | 'read-only\n' |
| 8748 | 'proxy, which becomes the "__dict__" attribute of the class ' |
| 8749 | 'object.\n' |
Ned Deily | 8b9173a | 2016-06-13 16:51:55 -0400 | [diff] [blame] | 8750 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8751 | 'See also:\n' |
| 8752 | '\n' |
| 8753 | ' **PEP 3135** - New super\n' |
| 8754 | ' Describes the implicit "__class__" closure reference\n' |
| 8755 | '\n' |
| 8756 | '\n' |
| 8757 | 'Metaclass example\n' |
| 8758 | '-----------------\n' |
| 8759 | '\n' |
| 8760 | 'The potential uses for metaclasses are boundless. Some ideas ' |
| 8761 | 'that have\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8762 | 'been explored include enum, logging, interface checking, ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8763 | 'automatic\n' |
| 8764 | 'delegation, automatic property creation, proxies, ' |
| 8765 | 'frameworks, and\n' |
| 8766 | 'automatic resource locking/synchronization.\n' |
| 8767 | '\n' |
| 8768 | 'Here is an example of a metaclass that uses an\n' |
| 8769 | '"collections.OrderedDict" to remember the order that class ' |
| 8770 | 'variables\n' |
| 8771 | 'are defined:\n' |
| 8772 | '\n' |
| 8773 | ' class OrderedClass(type):\n' |
| 8774 | '\n' |
| 8775 | ' @classmethod\n' |
| 8776 | ' def __prepare__(metacls, name, bases, **kwds):\n' |
| 8777 | ' return collections.OrderedDict()\n' |
| 8778 | '\n' |
| 8779 | ' def __new__(cls, name, bases, namespace, **kwds):\n' |
| 8780 | ' result = type.__new__(cls, name, bases, ' |
| 8781 | 'dict(namespace))\n' |
| 8782 | ' result.members = tuple(namespace)\n' |
| 8783 | ' return result\n' |
| 8784 | '\n' |
| 8785 | ' class A(metaclass=OrderedClass):\n' |
| 8786 | ' def one(self): pass\n' |
| 8787 | ' def two(self): pass\n' |
| 8788 | ' def three(self): pass\n' |
| 8789 | ' def four(self): pass\n' |
| 8790 | '\n' |
| 8791 | ' >>> A.members\n' |
| 8792 | " ('__module__', 'one', 'two', 'three', 'four')\n" |
| 8793 | '\n' |
| 8794 | 'When the class definition for *A* gets executed, the process ' |
| 8795 | 'begins\n' |
| 8796 | 'with calling the metaclass\'s "__prepare__()" method which ' |
| 8797 | 'returns an\n' |
| 8798 | 'empty "collections.OrderedDict". That mapping records the ' |
| 8799 | 'methods and\n' |
| 8800 | 'attributes of *A* as they are defined within the body of the ' |
| 8801 | 'class\n' |
| 8802 | 'statement. Once those definitions are executed, the ordered ' |
| 8803 | 'dictionary\n' |
| 8804 | 'is fully populated and the metaclass\'s "__new__()" method ' |
| 8805 | 'gets\n' |
| 8806 | 'invoked. That method builds the new type and it saves the ' |
| 8807 | 'ordered\n' |
| 8808 | 'dictionary keys in an attribute called "members".\n' |
| 8809 | '\n' |
| 8810 | '\n' |
| 8811 | 'Customizing instance and subclass checks\n' |
| 8812 | '========================================\n' |
| 8813 | '\n' |
| 8814 | 'The following methods are used to override the default ' |
| 8815 | 'behavior of the\n' |
| 8816 | '"isinstance()" and "issubclass()" built-in functions.\n' |
| 8817 | '\n' |
| 8818 | 'In particular, the metaclass "abc.ABCMeta" implements these ' |
| 8819 | 'methods in\n' |
| 8820 | 'order to allow the addition of Abstract Base Classes (ABCs) ' |
| 8821 | 'as\n' |
| 8822 | '"virtual base classes" to any class or type (including ' |
| 8823 | 'built-in\n' |
| 8824 | 'types), including other ABCs.\n' |
| 8825 | '\n' |
| 8826 | 'class.__instancecheck__(self, instance)\n' |
| 8827 | '\n' |
| 8828 | ' Return true if *instance* should be considered a (direct ' |
| 8829 | 'or\n' |
| 8830 | ' indirect) instance of *class*. If defined, called to ' |
| 8831 | 'implement\n' |
| 8832 | ' "isinstance(instance, class)".\n' |
| 8833 | '\n' |
| 8834 | 'class.__subclasscheck__(self, subclass)\n' |
| 8835 | '\n' |
| 8836 | ' Return true if *subclass* should be considered a (direct ' |
| 8837 | 'or\n' |
| 8838 | ' indirect) subclass of *class*. If defined, called to ' |
| 8839 | 'implement\n' |
| 8840 | ' "issubclass(subclass, class)".\n' |
| 8841 | '\n' |
| 8842 | 'Note that these methods are looked up on the type ' |
| 8843 | '(metaclass) of a\n' |
| 8844 | 'class. They cannot be defined as class methods in the ' |
| 8845 | 'actual class.\n' |
| 8846 | 'This is consistent with the lookup of special methods that ' |
| 8847 | 'are called\n' |
| 8848 | 'on instances, only in this case the instance is itself a ' |
| 8849 | 'class.\n' |
| 8850 | '\n' |
| 8851 | 'See also:\n' |
| 8852 | '\n' |
| 8853 | ' **PEP 3119** - Introducing Abstract Base Classes\n' |
| 8854 | ' Includes the specification for customizing ' |
| 8855 | '"isinstance()" and\n' |
| 8856 | ' "issubclass()" behavior through "__instancecheck__()" ' |
| 8857 | 'and\n' |
| 8858 | ' "__subclasscheck__()", with motivation for this ' |
| 8859 | 'functionality in\n' |
| 8860 | ' the context of adding Abstract Base Classes (see the ' |
| 8861 | '"abc"\n' |
| 8862 | ' module) to the language.\n' |
| 8863 | '\n' |
| 8864 | '\n' |
| 8865 | 'Emulating callable objects\n' |
| 8866 | '==========================\n' |
| 8867 | '\n' |
| 8868 | 'object.__call__(self[, args...])\n' |
| 8869 | '\n' |
| 8870 | ' Called when the instance is "called" as a function; if ' |
| 8871 | 'this method\n' |
| 8872 | ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' |
| 8873 | ' "x.__call__(arg1, arg2, ...)".\n' |
| 8874 | '\n' |
| 8875 | '\n' |
| 8876 | 'Emulating container types\n' |
| 8877 | '=========================\n' |
| 8878 | '\n' |
| 8879 | 'The following methods can be defined to implement container ' |
| 8880 | 'objects.\n' |
| 8881 | 'Containers usually are sequences (such as lists or tuples) ' |
| 8882 | 'or mappings\n' |
| 8883 | '(like dictionaries), but can represent other containers as ' |
| 8884 | 'well. The\n' |
| 8885 | 'first set of methods is used either to emulate a sequence or ' |
| 8886 | 'to\n' |
| 8887 | 'emulate a mapping; the difference is that for a sequence, ' |
| 8888 | 'the\n' |
| 8889 | 'allowable keys should be the integers *k* for which "0 <= k ' |
| 8890 | '< N" where\n' |
| 8891 | '*N* is the length of the sequence, or slice objects, which ' |
| 8892 | 'define a\n' |
| 8893 | 'range of items. It is also recommended that mappings ' |
| 8894 | 'provide the\n' |
| 8895 | 'methods "keys()", "values()", "items()", "get()", ' |
| 8896 | '"clear()",\n' |
| 8897 | '"setdefault()", "pop()", "popitem()", "copy()", and ' |
| 8898 | '"update()"\n' |
| 8899 | "behaving similar to those for Python's standard dictionary " |
| 8900 | 'objects.\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8901 | 'The "collections.abc" module provides a "MutableMapping" ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8902 | 'abstract base\n' |
| 8903 | 'class to help create those methods from a base set of ' |
| 8904 | '"__getitem__()",\n' |
| 8905 | '"__setitem__()", "__delitem__()", and "keys()". Mutable ' |
| 8906 | 'sequences\n' |
| 8907 | 'should provide methods "append()", "count()", "index()", ' |
| 8908 | '"extend()",\n' |
| 8909 | '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' |
| 8910 | 'like Python\n' |
| 8911 | 'standard list objects. Finally, sequence types should ' |
| 8912 | 'implement\n' |
| 8913 | 'addition (meaning concatenation) and multiplication ' |
| 8914 | '(meaning\n' |
| 8915 | 'repetition) by defining the methods "__add__()", ' |
| 8916 | '"__radd__()",\n' |
| 8917 | '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' |
| 8918 | 'described\n' |
| 8919 | 'below; they should not define other numerical operators. It ' |
| 8920 | 'is\n' |
| 8921 | 'recommended that both mappings and sequences implement the\n' |
| 8922 | '"__contains__()" method to allow efficient use of the "in" ' |
| 8923 | 'operator;\n' |
| 8924 | 'for mappings, "in" should search the mapping\'s keys; for ' |
| 8925 | 'sequences, it\n' |
| 8926 | 'should search through the values. It is further recommended ' |
| 8927 | 'that both\n' |
| 8928 | 'mappings and sequences implement the "__iter__()" method to ' |
| 8929 | 'allow\n' |
| 8930 | 'efficient iteration through the container; for mappings, ' |
| 8931 | '"__iter__()"\n' |
| 8932 | 'should be the same as "keys()"; for sequences, it should ' |
| 8933 | 'iterate\n' |
| 8934 | 'through the values.\n' |
| 8935 | '\n' |
| 8936 | 'object.__len__(self)\n' |
| 8937 | '\n' |
| 8938 | ' Called to implement the built-in function "len()". ' |
| 8939 | 'Should return\n' |
| 8940 | ' the length of the object, an integer ">=" 0. Also, an ' |
| 8941 | 'object that\n' |
| 8942 | ' doesn\'t define a "__bool__()" method and whose ' |
| 8943 | '"__len__()" method\n' |
| 8944 | ' returns zero is considered to be false in a Boolean ' |
| 8945 | 'context.\n' |
| 8946 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 8947 | ' **CPython implementation detail:** In CPython, the length ' |
| 8948 | 'is\n' |
| 8949 | ' required to be at most "sys.maxsize". If the length is ' |
| 8950 | 'larger than\n' |
| 8951 | ' "sys.maxsize" some features (such as "len()") may raise\n' |
| 8952 | ' "OverflowError". To prevent raising "OverflowError" by ' |
| 8953 | 'truth value\n' |
| 8954 | ' testing, an object must define a "__bool__()" method.\n' |
| 8955 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 8956 | 'object.__length_hint__(self)\n' |
| 8957 | '\n' |
| 8958 | ' Called to implement "operator.length_hint()". Should ' |
| 8959 | 'return an\n' |
| 8960 | ' estimated length for the object (which may be greater or ' |
| 8961 | 'less than\n' |
| 8962 | ' the actual length). The length must be an integer ">=" 0. ' |
| 8963 | 'This\n' |
| 8964 | ' method is purely an optimization and is never required ' |
| 8965 | 'for\n' |
| 8966 | ' correctness.\n' |
| 8967 | '\n' |
| 8968 | ' New in version 3.4.\n' |
| 8969 | '\n' |
| 8970 | 'Note: Slicing is done exclusively with the following three ' |
| 8971 | 'methods.\n' |
| 8972 | ' A call like\n' |
| 8973 | '\n' |
| 8974 | ' a[1:2] = b\n' |
| 8975 | '\n' |
| 8976 | ' is translated to\n' |
| 8977 | '\n' |
| 8978 | ' a[slice(1, 2, None)] = b\n' |
| 8979 | '\n' |
| 8980 | ' and so forth. Missing slice items are always filled in ' |
| 8981 | 'with "None".\n' |
| 8982 | '\n' |
| 8983 | 'object.__getitem__(self, key)\n' |
| 8984 | '\n' |
| 8985 | ' Called to implement evaluation of "self[key]". For ' |
| 8986 | 'sequence types,\n' |
| 8987 | ' the accepted keys should be integers and slice objects. ' |
| 8988 | 'Note that\n' |
| 8989 | ' the special interpretation of negative indexes (if the ' |
| 8990 | 'class wishes\n' |
| 8991 | ' to emulate a sequence type) is up to the "__getitem__()" ' |
| 8992 | 'method. If\n' |
| 8993 | ' *key* is of an inappropriate type, "TypeError" may be ' |
| 8994 | 'raised; if of\n' |
| 8995 | ' a value outside the set of indexes for the sequence ' |
| 8996 | '(after any\n' |
| 8997 | ' special interpretation of negative values), "IndexError" ' |
| 8998 | 'should be\n' |
| 8999 | ' raised. For mapping types, if *key* is missing (not in ' |
| 9000 | 'the\n' |
| 9001 | ' container), "KeyError" should be raised.\n' |
| 9002 | '\n' |
| 9003 | ' Note: "for" loops expect that an "IndexError" will be ' |
| 9004 | 'raised for\n' |
| 9005 | ' illegal indexes to allow proper detection of the end of ' |
| 9006 | 'the\n' |
| 9007 | ' sequence.\n' |
| 9008 | '\n' |
| 9009 | 'object.__missing__(self, key)\n' |
| 9010 | '\n' |
| 9011 | ' Called by "dict"."__getitem__()" to implement "self[key]" ' |
| 9012 | 'for dict\n' |
| 9013 | ' subclasses when key is not in the dictionary.\n' |
| 9014 | '\n' |
| 9015 | 'object.__setitem__(self, key, value)\n' |
| 9016 | '\n' |
| 9017 | ' Called to implement assignment to "self[key]". Same note ' |
| 9018 | 'as for\n' |
| 9019 | ' "__getitem__()". This should only be implemented for ' |
| 9020 | 'mappings if\n' |
| 9021 | ' the objects support changes to the values for keys, or if ' |
| 9022 | 'new keys\n' |
| 9023 | ' can be added, or for sequences if elements can be ' |
| 9024 | 'replaced. The\n' |
| 9025 | ' same exceptions should be raised for improper *key* ' |
| 9026 | 'values as for\n' |
| 9027 | ' the "__getitem__()" method.\n' |
| 9028 | '\n' |
| 9029 | 'object.__delitem__(self, key)\n' |
| 9030 | '\n' |
| 9031 | ' Called to implement deletion of "self[key]". Same note ' |
| 9032 | 'as for\n' |
| 9033 | ' "__getitem__()". This should only be implemented for ' |
| 9034 | 'mappings if\n' |
| 9035 | ' the objects support removal of keys, or for sequences if ' |
| 9036 | 'elements\n' |
| 9037 | ' can be removed from the sequence. The same exceptions ' |
| 9038 | 'should be\n' |
| 9039 | ' raised for improper *key* values as for the ' |
| 9040 | '"__getitem__()" method.\n' |
| 9041 | '\n' |
| 9042 | 'object.__iter__(self)\n' |
| 9043 | '\n' |
| 9044 | ' This method is called when an iterator is required for a ' |
| 9045 | 'container.\n' |
| 9046 | ' This method should return a new iterator object that can ' |
| 9047 | 'iterate\n' |
| 9048 | ' over all the objects in the container. For mappings, it ' |
| 9049 | 'should\n' |
| 9050 | ' iterate over the keys of the container.\n' |
| 9051 | '\n' |
| 9052 | ' Iterator objects also need to implement this method; they ' |
| 9053 | 'are\n' |
| 9054 | ' required to return themselves. For more information on ' |
| 9055 | 'iterator\n' |
| 9056 | ' objects, see Iterator Types.\n' |
| 9057 | '\n' |
| 9058 | 'object.__reversed__(self)\n' |
| 9059 | '\n' |
| 9060 | ' Called (if present) by the "reversed()" built-in to ' |
| 9061 | 'implement\n' |
| 9062 | ' reverse iteration. It should return a new iterator ' |
| 9063 | 'object that\n' |
| 9064 | ' iterates over all the objects in the container in reverse ' |
| 9065 | 'order.\n' |
| 9066 | '\n' |
| 9067 | ' If the "__reversed__()" method is not provided, the ' |
| 9068 | '"reversed()"\n' |
| 9069 | ' built-in will fall back to using the sequence protocol ' |
| 9070 | '("__len__()"\n' |
| 9071 | ' and "__getitem__()"). Objects that support the sequence ' |
| 9072 | 'protocol\n' |
| 9073 | ' should only provide "__reversed__()" if they can provide ' |
| 9074 | 'an\n' |
| 9075 | ' implementation that is more efficient than the one ' |
| 9076 | 'provided by\n' |
| 9077 | ' "reversed()".\n' |
| 9078 | '\n' |
| 9079 | 'The membership test operators ("in" and "not in") are ' |
| 9080 | 'normally\n' |
| 9081 | 'implemented as an iteration through a sequence. However, ' |
| 9082 | 'container\n' |
| 9083 | 'objects can supply the following special method with a more ' |
| 9084 | 'efficient\n' |
| 9085 | 'implementation, which also does not require the object be a ' |
| 9086 | 'sequence.\n' |
| 9087 | '\n' |
| 9088 | 'object.__contains__(self, item)\n' |
| 9089 | '\n' |
| 9090 | ' Called to implement membership test operators. Should ' |
| 9091 | 'return true\n' |
| 9092 | ' if *item* is in *self*, false otherwise. For mapping ' |
| 9093 | 'objects, this\n' |
| 9094 | ' should consider the keys of the mapping rather than the ' |
| 9095 | 'values or\n' |
| 9096 | ' the key-item pairs.\n' |
| 9097 | '\n' |
| 9098 | ' For objects that don\'t define "__contains__()", the ' |
| 9099 | 'membership test\n' |
| 9100 | ' first tries iteration via "__iter__()", then the old ' |
| 9101 | 'sequence\n' |
| 9102 | ' iteration protocol via "__getitem__()", see this section ' |
| 9103 | 'in the\n' |
| 9104 | ' language reference.\n' |
| 9105 | '\n' |
| 9106 | '\n' |
| 9107 | 'Emulating numeric types\n' |
| 9108 | '=======================\n' |
| 9109 | '\n' |
| 9110 | 'The following methods can be defined to emulate numeric ' |
| 9111 | 'objects.\n' |
| 9112 | 'Methods corresponding to operations that are not supported ' |
| 9113 | 'by the\n' |
| 9114 | 'particular kind of number implemented (e.g., bitwise ' |
| 9115 | 'operations for\n' |
| 9116 | 'non-integral numbers) should be left undefined.\n' |
| 9117 | '\n' |
| 9118 | 'object.__add__(self, other)\n' |
| 9119 | 'object.__sub__(self, other)\n' |
| 9120 | 'object.__mul__(self, other)\n' |
| 9121 | 'object.__matmul__(self, other)\n' |
| 9122 | 'object.__truediv__(self, other)\n' |
| 9123 | 'object.__floordiv__(self, other)\n' |
| 9124 | 'object.__mod__(self, other)\n' |
| 9125 | 'object.__divmod__(self, other)\n' |
| 9126 | 'object.__pow__(self, other[, modulo])\n' |
| 9127 | 'object.__lshift__(self, other)\n' |
| 9128 | 'object.__rshift__(self, other)\n' |
| 9129 | 'object.__and__(self, other)\n' |
| 9130 | 'object.__xor__(self, other)\n' |
| 9131 | 'object.__or__(self, other)\n' |
| 9132 | '\n' |
| 9133 | ' These methods are called to implement the binary ' |
| 9134 | 'arithmetic\n' |
| 9135 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 9136 | '"divmod()",\n' |
| 9137 | ' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, ' |
| 9138 | 'to\n' |
| 9139 | ' evaluate the expression "x + y", where *x* is an instance ' |
| 9140 | 'of a\n' |
| 9141 | ' class that has an "__add__()" method, "x.__add__(y)" is ' |
| 9142 | 'called.\n' |
| 9143 | ' The "__divmod__()" method should be the equivalent to ' |
| 9144 | 'using\n' |
| 9145 | ' "__floordiv__()" and "__mod__()"; it should not be ' |
| 9146 | 'related to\n' |
| 9147 | ' "__truediv__()". Note that "__pow__()" should be defined ' |
| 9148 | 'to accept\n' |
| 9149 | ' an optional third argument if the ternary version of the ' |
| 9150 | 'built-in\n' |
| 9151 | ' "pow()" function is to be supported.\n' |
| 9152 | '\n' |
| 9153 | ' If one of those methods does not support the operation ' |
| 9154 | 'with the\n' |
| 9155 | ' supplied arguments, it should return "NotImplemented".\n' |
| 9156 | '\n' |
| 9157 | 'object.__radd__(self, other)\n' |
| 9158 | 'object.__rsub__(self, other)\n' |
| 9159 | 'object.__rmul__(self, other)\n' |
| 9160 | 'object.__rmatmul__(self, other)\n' |
| 9161 | 'object.__rtruediv__(self, other)\n' |
| 9162 | 'object.__rfloordiv__(self, other)\n' |
| 9163 | 'object.__rmod__(self, other)\n' |
| 9164 | 'object.__rdivmod__(self, other)\n' |
| 9165 | 'object.__rpow__(self, other)\n' |
| 9166 | 'object.__rlshift__(self, other)\n' |
| 9167 | 'object.__rrshift__(self, other)\n' |
| 9168 | 'object.__rand__(self, other)\n' |
| 9169 | 'object.__rxor__(self, other)\n' |
| 9170 | 'object.__ror__(self, other)\n' |
| 9171 | '\n' |
| 9172 | ' These methods are called to implement the binary ' |
| 9173 | 'arithmetic\n' |
| 9174 | ' operations ("+", "-", "*", "@", "/", "//", "%", ' |
| 9175 | '"divmod()",\n' |
| 9176 | ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' |
| 9177 | '(swapped)\n' |
| 9178 | ' operands. These functions are only called if the left ' |
| 9179 | 'operand does\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 9180 | ' not support the corresponding operation [3] and the ' |
| 9181 | 'operands are of\n' |
| 9182 | ' different types. [4] For instance, to evaluate the ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9183 | 'expression "x -\n' |
| 9184 | ' y", where *y* is an instance of a class that has an ' |
| 9185 | '"__rsub__()"\n' |
| 9186 | ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' |
| 9187 | 'returns\n' |
| 9188 | ' *NotImplemented*.\n' |
| 9189 | '\n' |
| 9190 | ' Note that ternary "pow()" will not try calling ' |
| 9191 | '"__rpow__()" (the\n' |
| 9192 | ' coercion rules would become too complicated).\n' |
| 9193 | '\n' |
| 9194 | " Note: If the right operand's type is a subclass of the " |
| 9195 | 'left\n' |
| 9196 | " operand's type and that subclass provides the reflected " |
| 9197 | 'method\n' |
| 9198 | ' for the operation, this method will be called before ' |
| 9199 | 'the left\n' |
| 9200 | " operand's non-reflected method. This behavior allows " |
| 9201 | 'subclasses\n' |
| 9202 | " to override their ancestors' operations.\n" |
| 9203 | '\n' |
| 9204 | 'object.__iadd__(self, other)\n' |
| 9205 | 'object.__isub__(self, other)\n' |
| 9206 | 'object.__imul__(self, other)\n' |
| 9207 | 'object.__imatmul__(self, other)\n' |
| 9208 | 'object.__itruediv__(self, other)\n' |
| 9209 | 'object.__ifloordiv__(self, other)\n' |
| 9210 | 'object.__imod__(self, other)\n' |
| 9211 | 'object.__ipow__(self, other[, modulo])\n' |
| 9212 | 'object.__ilshift__(self, other)\n' |
| 9213 | 'object.__irshift__(self, other)\n' |
| 9214 | 'object.__iand__(self, other)\n' |
| 9215 | 'object.__ixor__(self, other)\n' |
| 9216 | 'object.__ior__(self, other)\n' |
| 9217 | '\n' |
| 9218 | ' These methods are called to implement the augmented ' |
| 9219 | 'arithmetic\n' |
| 9220 | ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' |
| 9221 | '"**=",\n' |
| 9222 | ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' |
| 9223 | 'attempt to\n' |
| 9224 | ' do the operation in-place (modifying *self*) and return ' |
| 9225 | 'the result\n' |
| 9226 | ' (which could be, but does not have to be, *self*). If a ' |
| 9227 | 'specific\n' |
| 9228 | ' method is not defined, the augmented assignment falls ' |
| 9229 | 'back to the\n' |
| 9230 | ' normal methods. For instance, if *x* is an instance of a ' |
| 9231 | 'class\n' |
| 9232 | ' with an "__iadd__()" method, "x += y" is equivalent to "x ' |
| 9233 | '=\n' |
| 9234 | ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' |
| 9235 | '"y.__radd__(x)" are\n' |
| 9236 | ' considered, as with the evaluation of "x + y". In ' |
| 9237 | 'certain\n' |
| 9238 | ' situations, augmented assignment can result in unexpected ' |
| 9239 | 'errors\n' |
| 9240 | " (see Why does a_tuple[i] += ['item'] raise an exception " |
| 9241 | 'when the\n' |
| 9242 | ' addition works?), but this behavior is in fact part of ' |
| 9243 | 'the data\n' |
| 9244 | ' model.\n' |
| 9245 | '\n' |
| 9246 | 'object.__neg__(self)\n' |
| 9247 | 'object.__pos__(self)\n' |
| 9248 | 'object.__abs__(self)\n' |
| 9249 | 'object.__invert__(self)\n' |
| 9250 | '\n' |
| 9251 | ' Called to implement the unary arithmetic operations ("-", ' |
| 9252 | '"+",\n' |
| 9253 | ' "abs()" and "~").\n' |
| 9254 | '\n' |
| 9255 | 'object.__complex__(self)\n' |
| 9256 | 'object.__int__(self)\n' |
| 9257 | 'object.__float__(self)\n' |
| 9258 | 'object.__round__(self[, n])\n' |
| 9259 | '\n' |
| 9260 | ' Called to implement the built-in functions "complex()", ' |
| 9261 | '"int()",\n' |
| 9262 | ' "float()" and "round()". Should return a value of the ' |
| 9263 | 'appropriate\n' |
| 9264 | ' type.\n' |
| 9265 | '\n' |
| 9266 | 'object.__index__(self)\n' |
| 9267 | '\n' |
| 9268 | ' Called to implement "operator.index()", and whenever ' |
| 9269 | 'Python needs\n' |
| 9270 | ' to losslessly convert the numeric object to an integer ' |
| 9271 | 'object (such\n' |
| 9272 | ' as in slicing, or in the built-in "bin()", "hex()" and ' |
| 9273 | '"oct()"\n' |
| 9274 | ' functions). Presence of this method indicates that the ' |
| 9275 | 'numeric\n' |
| 9276 | ' object is an integer type. Must return an integer.\n' |
| 9277 | '\n' |
| 9278 | ' Note: In order to have a coherent integer type class, ' |
| 9279 | 'when\n' |
| 9280 | ' "__index__()" is defined "__int__()" should also be ' |
| 9281 | 'defined, and\n' |
| 9282 | ' both should return the same value.\n' |
| 9283 | '\n' |
| 9284 | '\n' |
| 9285 | 'With Statement Context Managers\n' |
| 9286 | '===============================\n' |
| 9287 | '\n' |
| 9288 | 'A *context manager* is an object that defines the runtime ' |
| 9289 | 'context to\n' |
| 9290 | 'be established when executing a "with" statement. The ' |
| 9291 | 'context manager\n' |
| 9292 | 'handles the entry into, and the exit from, the desired ' |
| 9293 | 'runtime context\n' |
| 9294 | 'for the execution of the block of code. Context managers ' |
| 9295 | 'are normally\n' |
| 9296 | 'invoked using the "with" statement (described in section The ' |
| 9297 | 'with\n' |
| 9298 | 'statement), but can also be used by directly invoking their ' |
| 9299 | 'methods.\n' |
| 9300 | '\n' |
| 9301 | 'Typical uses of context managers include saving and ' |
| 9302 | 'restoring various\n' |
| 9303 | 'kinds of global state, locking and unlocking resources, ' |
| 9304 | 'closing opened\n' |
| 9305 | 'files, etc.\n' |
| 9306 | '\n' |
| 9307 | 'For more information on context managers, see Context ' |
| 9308 | 'Manager Types.\n' |
| 9309 | '\n' |
| 9310 | 'object.__enter__(self)\n' |
| 9311 | '\n' |
| 9312 | ' Enter the runtime context related to this object. The ' |
| 9313 | '"with"\n' |
| 9314 | " statement will bind this method's return value to the " |
| 9315 | 'target(s)\n' |
| 9316 | ' specified in the "as" clause of the statement, if any.\n' |
| 9317 | '\n' |
| 9318 | 'object.__exit__(self, exc_type, exc_value, traceback)\n' |
| 9319 | '\n' |
| 9320 | ' Exit the runtime context related to this object. The ' |
| 9321 | 'parameters\n' |
| 9322 | ' describe the exception that caused the context to be ' |
| 9323 | 'exited. If the\n' |
| 9324 | ' context was exited without an exception, all three ' |
| 9325 | 'arguments will\n' |
| 9326 | ' be "None".\n' |
| 9327 | '\n' |
| 9328 | ' If an exception is supplied, and the method wishes to ' |
| 9329 | 'suppress the\n' |
| 9330 | ' exception (i.e., prevent it from being propagated), it ' |
| 9331 | 'should\n' |
| 9332 | ' return a true value. Otherwise, the exception will be ' |
| 9333 | 'processed\n' |
| 9334 | ' normally upon exit from this method.\n' |
| 9335 | '\n' |
| 9336 | ' Note that "__exit__()" methods should not reraise the ' |
| 9337 | 'passed-in\n' |
| 9338 | " exception; this is the caller's responsibility.\n" |
| 9339 | '\n' |
| 9340 | 'See also:\n' |
| 9341 | '\n' |
| 9342 | ' **PEP 343** - The "with" statement\n' |
| 9343 | ' The specification, background, and examples for the ' |
| 9344 | 'Python "with"\n' |
| 9345 | ' statement.\n' |
| 9346 | '\n' |
| 9347 | '\n' |
| 9348 | 'Special method lookup\n' |
| 9349 | '=====================\n' |
| 9350 | '\n' |
| 9351 | 'For custom classes, implicit invocations of special methods ' |
| 9352 | 'are only\n' |
| 9353 | "guaranteed to work correctly if defined on an object's type, " |
| 9354 | 'not in\n' |
| 9355 | "the object's instance dictionary. That behaviour is the " |
| 9356 | 'reason why\n' |
| 9357 | 'the following code raises an exception:\n' |
| 9358 | '\n' |
| 9359 | ' >>> class C:\n' |
| 9360 | ' ... pass\n' |
| 9361 | ' ...\n' |
| 9362 | ' >>> c = C()\n' |
| 9363 | ' >>> c.__len__ = lambda: 5\n' |
| 9364 | ' >>> len(c)\n' |
| 9365 | ' Traceback (most recent call last):\n' |
| 9366 | ' File "<stdin>", line 1, in <module>\n' |
| 9367 | " TypeError: object of type 'C' has no len()\n" |
| 9368 | '\n' |
| 9369 | 'The rationale behind this behaviour lies with a number of ' |
| 9370 | 'special\n' |
| 9371 | 'methods such as "__hash__()" and "__repr__()" that are ' |
| 9372 | 'implemented by\n' |
| 9373 | 'all objects, including type objects. If the implicit lookup ' |
| 9374 | 'of these\n' |
| 9375 | 'methods used the conventional lookup process, they would ' |
| 9376 | 'fail when\n' |
| 9377 | 'invoked on the type object itself:\n' |
| 9378 | '\n' |
| 9379 | ' >>> 1 .__hash__() == hash(1)\n' |
| 9380 | ' True\n' |
| 9381 | ' >>> int.__hash__() == hash(int)\n' |
| 9382 | ' Traceback (most recent call last):\n' |
| 9383 | ' File "<stdin>", line 1, in <module>\n' |
| 9384 | " TypeError: descriptor '__hash__' of 'int' object needs an " |
| 9385 | 'argument\n' |
| 9386 | '\n' |
| 9387 | 'Incorrectly attempting to invoke an unbound method of a ' |
| 9388 | 'class in this\n' |
| 9389 | "way is sometimes referred to as 'metaclass confusion', and " |
| 9390 | 'is avoided\n' |
| 9391 | 'by bypassing the instance when looking up special methods:\n' |
| 9392 | '\n' |
| 9393 | ' >>> type(1).__hash__(1) == hash(1)\n' |
| 9394 | ' True\n' |
| 9395 | ' >>> type(int).__hash__(int) == hash(int)\n' |
| 9396 | ' True\n' |
| 9397 | '\n' |
| 9398 | 'In addition to bypassing any instance attributes in the ' |
| 9399 | 'interest of\n' |
| 9400 | 'correctness, implicit special method lookup generally also ' |
| 9401 | 'bypasses\n' |
| 9402 | 'the "__getattribute__()" method even of the object\'s ' |
| 9403 | 'metaclass:\n' |
| 9404 | '\n' |
| 9405 | ' >>> class Meta(type):\n' |
| 9406 | ' ... def __getattribute__(*args):\n' |
| 9407 | ' ... print("Metaclass getattribute invoked")\n' |
| 9408 | ' ... return type.__getattribute__(*args)\n' |
| 9409 | ' ...\n' |
| 9410 | ' >>> class C(object, metaclass=Meta):\n' |
| 9411 | ' ... def __len__(self):\n' |
| 9412 | ' ... return 10\n' |
| 9413 | ' ... def __getattribute__(*args):\n' |
| 9414 | ' ... print("Class getattribute invoked")\n' |
| 9415 | ' ... return object.__getattribute__(*args)\n' |
| 9416 | ' ...\n' |
| 9417 | ' >>> c = C()\n' |
| 9418 | ' >>> c.__len__() # Explicit lookup via ' |
| 9419 | 'instance\n' |
| 9420 | ' Class getattribute invoked\n' |
| 9421 | ' 10\n' |
| 9422 | ' >>> type(c).__len__(c) # Explicit lookup via ' |
| 9423 | 'type\n' |
| 9424 | ' Metaclass getattribute invoked\n' |
| 9425 | ' 10\n' |
| 9426 | ' >>> len(c) # Implicit lookup\n' |
| 9427 | ' 10\n' |
| 9428 | '\n' |
| 9429 | 'Bypassing the "__getattribute__()" machinery in this fashion ' |
| 9430 | 'provides\n' |
| 9431 | 'significant scope for speed optimisations within the ' |
| 9432 | 'interpreter, at\n' |
| 9433 | 'the cost of some flexibility in the handling of special ' |
| 9434 | 'methods (the\n' |
| 9435 | 'special method *must* be set on the class object itself in ' |
| 9436 | 'order to be\n' |
| 9437 | 'consistently invoked by the interpreter).\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9438 | 'string-methods': 'String Methods\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9439 | '**************\n' |
| 9440 | '\n' |
| 9441 | 'Strings implement all of the common sequence operations, ' |
| 9442 | 'along with\n' |
| 9443 | 'the additional methods described below.\n' |
| 9444 | '\n' |
| 9445 | 'Strings also support two styles of string formatting, one ' |
| 9446 | 'providing a\n' |
| 9447 | 'large degree of flexibility and customization (see ' |
| 9448 | '"str.format()",\n' |
| 9449 | 'Format String Syntax and Custom String Formatting) and the ' |
| 9450 | 'other based\n' |
| 9451 | 'on C "printf" style formatting that handles a narrower ' |
| 9452 | 'range of types\n' |
| 9453 | 'and is slightly harder to use correctly, but is often ' |
| 9454 | 'faster for the\n' |
| 9455 | 'cases it can handle (printf-style String Formatting).\n' |
| 9456 | '\n' |
| 9457 | 'The Text Processing Services section of the standard ' |
| 9458 | 'library covers a\n' |
| 9459 | 'number of other modules that provide various text related ' |
| 9460 | 'utilities\n' |
| 9461 | '(including regular expression support in the "re" ' |
| 9462 | 'module).\n' |
| 9463 | '\n' |
| 9464 | 'str.capitalize()\n' |
| 9465 | '\n' |
| 9466 | ' Return a copy of the string with its first character ' |
| 9467 | 'capitalized\n' |
| 9468 | ' and the rest lowercased.\n' |
| 9469 | '\n' |
| 9470 | 'str.casefold()\n' |
| 9471 | '\n' |
| 9472 | ' Return a casefolded copy of the string. Casefolded ' |
| 9473 | 'strings may be\n' |
| 9474 | ' used for caseless matching.\n' |
| 9475 | '\n' |
| 9476 | ' Casefolding is similar to lowercasing but more ' |
| 9477 | 'aggressive because\n' |
| 9478 | ' it is intended to remove all case distinctions in a ' |
| 9479 | 'string. For\n' |
| 9480 | ' example, the German lowercase letter "\'ß\'" is ' |
| 9481 | 'equivalent to ""ss"".\n' |
| 9482 | ' Since it is already lowercase, "lower()" would do ' |
| 9483 | 'nothing to "\'ß\'";\n' |
| 9484 | ' "casefold()" converts it to ""ss"".\n' |
| 9485 | '\n' |
| 9486 | ' The casefolding algorithm is described in section 3.13 ' |
| 9487 | 'of the\n' |
| 9488 | ' Unicode Standard.\n' |
| 9489 | '\n' |
| 9490 | ' New in version 3.3.\n' |
| 9491 | '\n' |
| 9492 | 'str.center(width[, fillchar])\n' |
| 9493 | '\n' |
| 9494 | ' Return centered in a string of length *width*. Padding ' |
| 9495 | 'is done\n' |
| 9496 | ' using the specified *fillchar* (default is an ASCII ' |
| 9497 | 'space). The\n' |
| 9498 | ' original string is returned if *width* is less than or ' |
| 9499 | 'equal to\n' |
| 9500 | ' "len(s)".\n' |
| 9501 | '\n' |
| 9502 | 'str.count(sub[, start[, end]])\n' |
| 9503 | '\n' |
| 9504 | ' Return the number of non-overlapping occurrences of ' |
| 9505 | 'substring *sub*\n' |
| 9506 | ' in the range [*start*, *end*]. Optional arguments ' |
| 9507 | '*start* and\n' |
| 9508 | ' *end* are interpreted as in slice notation.\n' |
| 9509 | '\n' |
| 9510 | 'str.encode(encoding="utf-8", errors="strict")\n' |
| 9511 | '\n' |
| 9512 | ' Return an encoded version of the string as a bytes ' |
| 9513 | 'object. Default\n' |
| 9514 | ' encoding is "\'utf-8\'". *errors* may be given to set a ' |
| 9515 | 'different\n' |
| 9516 | ' error handling scheme. The default for *errors* is ' |
| 9517 | '"\'strict\'",\n' |
| 9518 | ' meaning that encoding errors raise a "UnicodeError". ' |
| 9519 | 'Other possible\n' |
| 9520 | ' values are "\'ignore\'", "\'replace\'", ' |
| 9521 | '"\'xmlcharrefreplace\'",\n' |
| 9522 | ' "\'backslashreplace\'" and any other name registered ' |
| 9523 | 'via\n' |
| 9524 | ' "codecs.register_error()", see section Error Handlers. ' |
| 9525 | 'For a list\n' |
| 9526 | ' of possible encodings, see section Standard Encodings.\n' |
| 9527 | '\n' |
| 9528 | ' Changed in version 3.1: Support for keyword arguments ' |
| 9529 | 'added.\n' |
| 9530 | '\n' |
| 9531 | 'str.endswith(suffix[, start[, end]])\n' |
| 9532 | '\n' |
| 9533 | ' Return "True" if the string ends with the specified ' |
| 9534 | '*suffix*,\n' |
| 9535 | ' otherwise return "False". *suffix* can also be a tuple ' |
| 9536 | 'of suffixes\n' |
| 9537 | ' to look for. With optional *start*, test beginning at ' |
| 9538 | 'that\n' |
| 9539 | ' position. With optional *end*, stop comparing at that ' |
| 9540 | 'position.\n' |
| 9541 | '\n' |
| 9542 | 'str.expandtabs(tabsize=8)\n' |
| 9543 | '\n' |
| 9544 | ' Return a copy of the string where all tab characters ' |
| 9545 | 'are replaced\n' |
| 9546 | ' by one or more spaces, depending on the current column ' |
| 9547 | 'and the\n' |
| 9548 | ' given tab size. Tab positions occur every *tabsize* ' |
| 9549 | 'characters\n' |
| 9550 | ' (default is 8, giving tab positions at columns 0, 8, 16 ' |
| 9551 | 'and so on).\n' |
| 9552 | ' To expand the string, the current column is set to zero ' |
| 9553 | 'and the\n' |
| 9554 | ' string is examined character by character. If the ' |
| 9555 | 'character is a\n' |
| 9556 | ' tab ("\\t"), one or more space characters are inserted ' |
| 9557 | 'in the result\n' |
| 9558 | ' until the current column is equal to the next tab ' |
| 9559 | 'position. (The\n' |
| 9560 | ' tab character itself is not copied.) If the character ' |
| 9561 | 'is a newline\n' |
| 9562 | ' ("\\n") or return ("\\r"), it is copied and the current ' |
| 9563 | 'column is\n' |
| 9564 | ' reset to zero. Any other character is copied unchanged ' |
| 9565 | 'and the\n' |
| 9566 | ' current column is incremented by one regardless of how ' |
| 9567 | 'the\n' |
| 9568 | ' character is represented when printed.\n' |
| 9569 | '\n' |
| 9570 | " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n" |
| 9571 | " '01 012 0123 01234'\n" |
| 9572 | " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n" |
| 9573 | " '01 012 0123 01234'\n" |
| 9574 | '\n' |
| 9575 | 'str.find(sub[, start[, end]])\n' |
| 9576 | '\n' |
| 9577 | ' Return the lowest index in the string where substring ' |
| 9578 | '*sub* is\n' |
| 9579 | ' found within the slice "s[start:end]". Optional ' |
| 9580 | 'arguments *start*\n' |
| 9581 | ' and *end* are interpreted as in slice notation. Return ' |
| 9582 | '"-1" if\n' |
| 9583 | ' *sub* is not found.\n' |
| 9584 | '\n' |
| 9585 | ' Note: The "find()" method should be used only if you ' |
| 9586 | 'need to know\n' |
| 9587 | ' the position of *sub*. To check if *sub* is a ' |
| 9588 | 'substring or not,\n' |
| 9589 | ' use the "in" operator:\n' |
| 9590 | '\n' |
| 9591 | " >>> 'Py' in 'Python'\n" |
| 9592 | ' True\n' |
| 9593 | '\n' |
| 9594 | 'str.format(*args, **kwargs)\n' |
| 9595 | '\n' |
| 9596 | ' Perform a string formatting operation. The string on ' |
| 9597 | 'which this\n' |
| 9598 | ' method is called can contain literal text or ' |
| 9599 | 'replacement fields\n' |
| 9600 | ' delimited by braces "{}". Each replacement field ' |
| 9601 | 'contains either\n' |
| 9602 | ' the numeric index of a positional argument, or the name ' |
| 9603 | 'of a\n' |
| 9604 | ' keyword argument. Returns a copy of the string where ' |
| 9605 | 'each\n' |
| 9606 | ' replacement field is replaced with the string value of ' |
| 9607 | 'the\n' |
| 9608 | ' corresponding argument.\n' |
| 9609 | '\n' |
| 9610 | ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n' |
| 9611 | " 'The sum of 1 + 2 is 3'\n" |
| 9612 | '\n' |
| 9613 | ' See Format String Syntax for a description of the ' |
| 9614 | 'various\n' |
| 9615 | ' formatting options that can be specified in format ' |
| 9616 | 'strings.\n' |
| 9617 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 9618 | ' Note: When formatting a number ("int", "float", "float" ' |
| 9619 | 'and\n' |
| 9620 | ' subclasses) with the "n" type (ex: ' |
| 9621 | '"\'{:n}\'.format(1234)"), the\n' |
| 9622 | ' function sets temporarily the "LC_CTYPE" locale to ' |
| 9623 | 'the\n' |
| 9624 | ' "LC_NUMERIC" locale to decode "decimal_point" and ' |
| 9625 | '"thousands_sep"\n' |
| 9626 | ' fields of "localeconv()" if they are non-ASCII or ' |
| 9627 | 'longer than 1\n' |
| 9628 | ' byte, and the "LC_NUMERIC" locale is different than ' |
| 9629 | 'the\n' |
| 9630 | ' "LC_CTYPE" locale. This temporary change affects ' |
| 9631 | 'other threads.\n' |
| 9632 | '\n' |
| 9633 | ' Changed in version 3.7: When formatting a number with ' |
| 9634 | 'the "n" type,\n' |
| 9635 | ' the function sets temporarily the "LC_CTYPE" locale to ' |
| 9636 | 'the\n' |
| 9637 | ' "LC_NUMERIC" locale in some cases.\n' |
| 9638 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9639 | 'str.format_map(mapping)\n' |
| 9640 | '\n' |
| 9641 | ' Similar to "str.format(**mapping)", except that ' |
| 9642 | '"mapping" is used\n' |
| 9643 | ' directly and not copied to a "dict". This is useful if ' |
| 9644 | 'for example\n' |
| 9645 | ' "mapping" is a dict subclass:\n' |
| 9646 | '\n' |
| 9647 | ' >>> class Default(dict):\n' |
| 9648 | ' ... def __missing__(self, key):\n' |
| 9649 | ' ... return key\n' |
| 9650 | ' ...\n' |
| 9651 | " >>> '{name} was born in " |
| 9652 | "{country}'.format_map(Default(name='Guido'))\n" |
| 9653 | " 'Guido was born in country'\n" |
| 9654 | '\n' |
| 9655 | ' New in version 3.2.\n' |
| 9656 | '\n' |
| 9657 | 'str.index(sub[, start[, end]])\n' |
| 9658 | '\n' |
| 9659 | ' Like "find()", but raise "ValueError" when the ' |
| 9660 | 'substring is not\n' |
| 9661 | ' found.\n' |
| 9662 | '\n' |
| 9663 | 'str.isalnum()\n' |
| 9664 | '\n' |
| 9665 | ' Return true if all characters in the string are ' |
| 9666 | 'alphanumeric and\n' |
| 9667 | ' there is at least one character, false otherwise. A ' |
| 9668 | 'character "c"\n' |
| 9669 | ' is alphanumeric if one of the following returns ' |
| 9670 | '"True":\n' |
| 9671 | ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or ' |
| 9672 | '"c.isnumeric()".\n' |
| 9673 | '\n' |
| 9674 | 'str.isalpha()\n' |
| 9675 | '\n' |
| 9676 | ' Return true if all characters in the string are ' |
| 9677 | 'alphabetic and\n' |
| 9678 | ' there is at least one character, false otherwise. ' |
| 9679 | 'Alphabetic\n' |
| 9680 | ' characters are those characters defined in the Unicode ' |
| 9681 | 'character\n' |
| 9682 | ' database as "Letter", i.e., those with general category ' |
| 9683 | 'property\n' |
| 9684 | ' being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note ' |
| 9685 | 'that this is\n' |
| 9686 | ' different from the "Alphabetic" property defined in the ' |
| 9687 | 'Unicode\n' |
| 9688 | ' Standard.\n' |
| 9689 | '\n' |
Ned Deily | 6e41cd9 | 2018-01-30 18:48:26 -0500 | [diff] [blame] | 9690 | 'str.isascii()\n' |
| 9691 | '\n' |
| 9692 | ' Return true if the string is empty or all characters in ' |
| 9693 | 'the string\n' |
| 9694 | ' are ASCII, false otherwise. ASCII characters have code ' |
| 9695 | 'points in\n' |
| 9696 | ' the range U+0000-U+007F.\n' |
| 9697 | '\n' |
| 9698 | ' New in version 3.7.\n' |
| 9699 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9700 | 'str.isdecimal()\n' |
| 9701 | '\n' |
| 9702 | ' Return true if all characters in the string are decimal ' |
| 9703 | 'characters\n' |
| 9704 | ' and there is at least one character, false otherwise. ' |
| 9705 | 'Decimal\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9706 | ' characters are those that can be used to form numbers ' |
| 9707 | 'in base 10,\n' |
| 9708 | ' e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally a ' |
| 9709 | 'decimal character\n' |
| 9710 | ' is a character in the Unicode General Category "Nd".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9711 | '\n' |
| 9712 | 'str.isdigit()\n' |
| 9713 | '\n' |
| 9714 | ' Return true if all characters in the string are digits ' |
| 9715 | 'and there is\n' |
| 9716 | ' at least one character, false otherwise. Digits ' |
| 9717 | 'include decimal\n' |
| 9718 | ' characters and digits that need special handling, such ' |
| 9719 | 'as the\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9720 | ' compatibility superscript digits. This covers digits ' |
| 9721 | 'which cannot\n' |
| 9722 | ' be used to form numbers in base 10, like the Kharosthi ' |
| 9723 | 'numbers.\n' |
| 9724 | ' Formally, a digit is a character that has the property ' |
| 9725 | 'value\n' |
| 9726 | ' Numeric_Type=Digit or Numeric_Type=Decimal.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9727 | '\n' |
| 9728 | 'str.isidentifier()\n' |
| 9729 | '\n' |
| 9730 | ' Return true if the string is a valid identifier ' |
| 9731 | 'according to the\n' |
| 9732 | ' language definition, section Identifiers and keywords.\n' |
| 9733 | '\n' |
| 9734 | ' Use "keyword.iskeyword()" to test for reserved ' |
| 9735 | 'identifiers such as\n' |
| 9736 | ' "def" and "class".\n' |
| 9737 | '\n' |
| 9738 | 'str.islower()\n' |
| 9739 | '\n' |
| 9740 | ' Return true if all cased characters [4] in the string ' |
| 9741 | 'are lowercase\n' |
| 9742 | ' and there is at least one cased character, false ' |
| 9743 | 'otherwise.\n' |
| 9744 | '\n' |
| 9745 | 'str.isnumeric()\n' |
| 9746 | '\n' |
| 9747 | ' Return true if all characters in the string are numeric ' |
| 9748 | 'characters,\n' |
| 9749 | ' and there is at least one character, false otherwise. ' |
| 9750 | 'Numeric\n' |
| 9751 | ' characters include digit characters, and all characters ' |
| 9752 | 'that have\n' |
| 9753 | ' the Unicode numeric value property, e.g. U+2155, VULGAR ' |
| 9754 | 'FRACTION\n' |
| 9755 | ' ONE FIFTH. Formally, numeric characters are those with ' |
| 9756 | 'the\n' |
| 9757 | ' property value Numeric_Type=Digit, Numeric_Type=Decimal ' |
| 9758 | 'or\n' |
| 9759 | ' Numeric_Type=Numeric.\n' |
| 9760 | '\n' |
| 9761 | 'str.isprintable()\n' |
| 9762 | '\n' |
| 9763 | ' Return true if all characters in the string are ' |
| 9764 | 'printable or the\n' |
| 9765 | ' string is empty, false otherwise. Nonprintable ' |
| 9766 | 'characters are\n' |
| 9767 | ' those characters defined in the Unicode character ' |
| 9768 | 'database as\n' |
| 9769 | ' "Other" or "Separator", excepting the ASCII space ' |
| 9770 | '(0x20) which is\n' |
| 9771 | ' considered printable. (Note that printable characters ' |
| 9772 | 'in this\n' |
| 9773 | ' context are those which should not be escaped when ' |
| 9774 | '"repr()" is\n' |
| 9775 | ' invoked on a string. It has no bearing on the handling ' |
| 9776 | 'of strings\n' |
| 9777 | ' written to "sys.stdout" or "sys.stderr".)\n' |
| 9778 | '\n' |
| 9779 | 'str.isspace()\n' |
| 9780 | '\n' |
| 9781 | ' Return true if there are only whitespace characters in ' |
| 9782 | 'the string\n' |
| 9783 | ' and there is at least one character, false otherwise. ' |
| 9784 | 'Whitespace\n' |
| 9785 | ' characters are those characters defined in the Unicode ' |
| 9786 | 'character\n' |
| 9787 | ' database as "Other" or "Separator" and those with ' |
| 9788 | 'bidirectional\n' |
| 9789 | ' property being one of "WS", "B", or "S".\n' |
| 9790 | '\n' |
| 9791 | 'str.istitle()\n' |
| 9792 | '\n' |
| 9793 | ' Return true if the string is a titlecased string and ' |
| 9794 | 'there is at\n' |
| 9795 | ' least one character, for example uppercase characters ' |
| 9796 | 'may only\n' |
| 9797 | ' follow uncased characters and lowercase characters only ' |
| 9798 | 'cased ones.\n' |
| 9799 | ' Return false otherwise.\n' |
| 9800 | '\n' |
| 9801 | 'str.isupper()\n' |
| 9802 | '\n' |
| 9803 | ' Return true if all cased characters [4] in the string ' |
| 9804 | 'are uppercase\n' |
| 9805 | ' and there is at least one cased character, false ' |
| 9806 | 'otherwise.\n' |
| 9807 | '\n' |
| 9808 | 'str.join(iterable)\n' |
| 9809 | '\n' |
| 9810 | ' Return a string which is the concatenation of the ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9811 | 'strings in\n' |
| 9812 | ' *iterable*. A "TypeError" will be raised if there are ' |
| 9813 | 'any non-\n' |
| 9814 | ' string values in *iterable*, including "bytes" ' |
| 9815 | 'objects. The\n' |
| 9816 | ' separator between elements is the string providing this ' |
| 9817 | 'method.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9818 | '\n' |
| 9819 | 'str.ljust(width[, fillchar])\n' |
| 9820 | '\n' |
| 9821 | ' Return the string left justified in a string of length ' |
| 9822 | '*width*.\n' |
| 9823 | ' Padding is done using the specified *fillchar* (default ' |
| 9824 | 'is an ASCII\n' |
| 9825 | ' space). The original string is returned if *width* is ' |
| 9826 | 'less than or\n' |
| 9827 | ' equal to "len(s)".\n' |
| 9828 | '\n' |
| 9829 | 'str.lower()\n' |
| 9830 | '\n' |
| 9831 | ' Return a copy of the string with all the cased ' |
| 9832 | 'characters [4]\n' |
| 9833 | ' converted to lowercase.\n' |
| 9834 | '\n' |
| 9835 | ' The lowercasing algorithm used is described in section ' |
| 9836 | '3.13 of the\n' |
| 9837 | ' Unicode Standard.\n' |
| 9838 | '\n' |
| 9839 | 'str.lstrip([chars])\n' |
| 9840 | '\n' |
| 9841 | ' Return a copy of the string with leading characters ' |
| 9842 | 'removed. The\n' |
| 9843 | ' *chars* argument is a string specifying the set of ' |
| 9844 | 'characters to be\n' |
| 9845 | ' removed. If omitted or "None", the *chars* argument ' |
| 9846 | 'defaults to\n' |
| 9847 | ' removing whitespace. The *chars* argument is not a ' |
| 9848 | 'prefix; rather,\n' |
| 9849 | ' all combinations of its values are stripped:\n' |
| 9850 | '\n' |
| 9851 | " >>> ' spacious '.lstrip()\n" |
| 9852 | " 'spacious '\n" |
| 9853 | " >>> 'www.example.com'.lstrip('cmowz.')\n" |
| 9854 | " 'example.com'\n" |
| 9855 | '\n' |
| 9856 | 'static str.maketrans(x[, y[, z]])\n' |
| 9857 | '\n' |
| 9858 | ' This static method returns a translation table usable ' |
| 9859 | 'for\n' |
| 9860 | ' "str.translate()".\n' |
| 9861 | '\n' |
| 9862 | ' If there is only one argument, it must be a dictionary ' |
| 9863 | 'mapping\n' |
| 9864 | ' Unicode ordinals (integers) or characters (strings of ' |
| 9865 | 'length 1) to\n' |
| 9866 | ' Unicode ordinals, strings (of arbitrary lengths) or ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9867 | '"None".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9868 | ' Character keys will then be converted to ordinals.\n' |
| 9869 | '\n' |
| 9870 | ' If there are two arguments, they must be strings of ' |
| 9871 | 'equal length,\n' |
| 9872 | ' and in the resulting dictionary, each character in x ' |
| 9873 | 'will be mapped\n' |
| 9874 | ' to the character at the same position in y. If there ' |
| 9875 | 'is a third\n' |
| 9876 | ' argument, it must be a string, whose characters will be ' |
| 9877 | 'mapped to\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 9878 | ' "None" in the result.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 9879 | '\n' |
| 9880 | 'str.partition(sep)\n' |
| 9881 | '\n' |
| 9882 | ' Split the string at the first occurrence of *sep*, and ' |
| 9883 | 'return a\n' |
| 9884 | ' 3-tuple containing the part before the separator, the ' |
| 9885 | 'separator\n' |
| 9886 | ' itself, and the part after the separator. If the ' |
| 9887 | 'separator is not\n' |
| 9888 | ' found, return a 3-tuple containing the string itself, ' |
| 9889 | 'followed by\n' |
| 9890 | ' two empty strings.\n' |
| 9891 | '\n' |
| 9892 | 'str.replace(old, new[, count])\n' |
| 9893 | '\n' |
| 9894 | ' Return a copy of the string with all occurrences of ' |
| 9895 | 'substring *old*\n' |
| 9896 | ' replaced by *new*. If the optional argument *count* is ' |
| 9897 | 'given, only\n' |
| 9898 | ' the first *count* occurrences are replaced.\n' |
| 9899 | '\n' |
| 9900 | 'str.rfind(sub[, start[, end]])\n' |
| 9901 | '\n' |
| 9902 | ' Return the highest index in the string where substring ' |
| 9903 | '*sub* is\n' |
| 9904 | ' found, such that *sub* is contained within ' |
| 9905 | '"s[start:end]".\n' |
| 9906 | ' Optional arguments *start* and *end* are interpreted as ' |
| 9907 | 'in slice\n' |
| 9908 | ' notation. Return "-1" on failure.\n' |
| 9909 | '\n' |
| 9910 | 'str.rindex(sub[, start[, end]])\n' |
| 9911 | '\n' |
| 9912 | ' Like "rfind()" but raises "ValueError" when the ' |
| 9913 | 'substring *sub* is\n' |
| 9914 | ' not found.\n' |
| 9915 | '\n' |
| 9916 | 'str.rjust(width[, fillchar])\n' |
| 9917 | '\n' |
| 9918 | ' Return the string right justified in a string of length ' |
| 9919 | '*width*.\n' |
| 9920 | ' Padding is done using the specified *fillchar* (default ' |
| 9921 | 'is an ASCII\n' |
| 9922 | ' space). The original string is returned if *width* is ' |
| 9923 | 'less than or\n' |
| 9924 | ' equal to "len(s)".\n' |
| 9925 | '\n' |
| 9926 | 'str.rpartition(sep)\n' |
| 9927 | '\n' |
| 9928 | ' Split the string at the last occurrence of *sep*, and ' |
| 9929 | 'return a\n' |
| 9930 | ' 3-tuple containing the part before the separator, the ' |
| 9931 | 'separator\n' |
| 9932 | ' itself, and the part after the separator. If the ' |
| 9933 | 'separator is not\n' |
| 9934 | ' found, return a 3-tuple containing two empty strings, ' |
| 9935 | 'followed by\n' |
| 9936 | ' the string itself.\n' |
| 9937 | '\n' |
| 9938 | 'str.rsplit(sep=None, maxsplit=-1)\n' |
| 9939 | '\n' |
| 9940 | ' Return a list of the words in the string, using *sep* ' |
| 9941 | 'as the\n' |
| 9942 | ' delimiter string. If *maxsplit* is given, at most ' |
| 9943 | '*maxsplit* splits\n' |
| 9944 | ' are done, the *rightmost* ones. If *sep* is not ' |
| 9945 | 'specified or\n' |
| 9946 | ' "None", any whitespace string is a separator. Except ' |
| 9947 | 'for splitting\n' |
| 9948 | ' from the right, "rsplit()" behaves like "split()" which ' |
| 9949 | 'is\n' |
| 9950 | ' described in detail below.\n' |
| 9951 | '\n' |
| 9952 | 'str.rstrip([chars])\n' |
| 9953 | '\n' |
| 9954 | ' Return a copy of the string with trailing characters ' |
| 9955 | 'removed. The\n' |
| 9956 | ' *chars* argument is a string specifying the set of ' |
| 9957 | 'characters to be\n' |
| 9958 | ' removed. If omitted or "None", the *chars* argument ' |
| 9959 | 'defaults to\n' |
| 9960 | ' removing whitespace. The *chars* argument is not a ' |
| 9961 | 'suffix; rather,\n' |
| 9962 | ' all combinations of its values are stripped:\n' |
| 9963 | '\n' |
| 9964 | " >>> ' spacious '.rstrip()\n" |
| 9965 | " ' spacious'\n" |
| 9966 | " >>> 'mississippi'.rstrip('ipz')\n" |
| 9967 | " 'mississ'\n" |
| 9968 | '\n' |
| 9969 | 'str.split(sep=None, maxsplit=-1)\n' |
| 9970 | '\n' |
| 9971 | ' Return a list of the words in the string, using *sep* ' |
| 9972 | 'as the\n' |
| 9973 | ' delimiter string. If *maxsplit* is given, at most ' |
| 9974 | '*maxsplit*\n' |
| 9975 | ' splits are done (thus, the list will have at most ' |
| 9976 | '"maxsplit+1"\n' |
| 9977 | ' elements). If *maxsplit* is not specified or "-1", ' |
| 9978 | 'then there is\n' |
| 9979 | ' no limit on the number of splits (all possible splits ' |
| 9980 | 'are made).\n' |
| 9981 | '\n' |
| 9982 | ' If *sep* is given, consecutive delimiters are not ' |
| 9983 | 'grouped together\n' |
| 9984 | ' and are deemed to delimit empty strings (for example,\n' |
| 9985 | ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', ' |
| 9986 | '\'2\']"). The *sep* argument\n' |
| 9987 | ' may consist of multiple characters (for example,\n' |
| 9988 | ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', ' |
| 9989 | '\'3\']"). Splitting an\n' |
| 9990 | ' empty string with a specified separator returns ' |
| 9991 | '"[\'\']".\n' |
| 9992 | '\n' |
| 9993 | ' For example:\n' |
| 9994 | '\n' |
| 9995 | " >>> '1,2,3'.split(',')\n" |
| 9996 | " ['1', '2', '3']\n" |
| 9997 | " >>> '1,2,3'.split(',', maxsplit=1)\n" |
| 9998 | " ['1', '2,3']\n" |
| 9999 | " >>> '1,2,,3,'.split(',')\n" |
| 10000 | " ['1', '2', '', '3', '']\n" |
| 10001 | '\n' |
| 10002 | ' If *sep* is not specified or is "None", a different ' |
| 10003 | 'splitting\n' |
| 10004 | ' algorithm is applied: runs of consecutive whitespace ' |
| 10005 | 'are regarded\n' |
| 10006 | ' as a single separator, and the result will contain no ' |
| 10007 | 'empty strings\n' |
| 10008 | ' at the start or end if the string has leading or ' |
| 10009 | 'trailing\n' |
| 10010 | ' whitespace. Consequently, splitting an empty string or ' |
| 10011 | 'a string\n' |
| 10012 | ' consisting of just whitespace with a "None" separator ' |
| 10013 | 'returns "[]".\n' |
| 10014 | '\n' |
| 10015 | ' For example:\n' |
| 10016 | '\n' |
| 10017 | " >>> '1 2 3'.split()\n" |
| 10018 | " ['1', '2', '3']\n" |
| 10019 | " >>> '1 2 3'.split(maxsplit=1)\n" |
| 10020 | " ['1', '2 3']\n" |
| 10021 | " >>> ' 1 2 3 '.split()\n" |
| 10022 | " ['1', '2', '3']\n" |
| 10023 | '\n' |
| 10024 | 'str.splitlines([keepends])\n' |
| 10025 | '\n' |
| 10026 | ' Return a list of the lines in the string, breaking at ' |
| 10027 | 'line\n' |
| 10028 | ' boundaries. Line breaks are not included in the ' |
| 10029 | 'resulting list\n' |
| 10030 | ' unless *keepends* is given and true.\n' |
| 10031 | '\n' |
| 10032 | ' This method splits on the following line boundaries. ' |
| 10033 | 'In\n' |
| 10034 | ' particular, the boundaries are a superset of *universal ' |
| 10035 | 'newlines*.\n' |
| 10036 | '\n' |
| 10037 | ' ' |
| 10038 | '+-------------------------+-------------------------------+\n' |
| 10039 | ' | Representation | ' |
| 10040 | 'Description |\n' |
| 10041 | ' ' |
| 10042 | '+=========================+===============================+\n' |
| 10043 | ' | "\\n" | Line ' |
| 10044 | 'Feed |\n' |
| 10045 | ' ' |
| 10046 | '+-------------------------+-------------------------------+\n' |
| 10047 | ' | "\\r" | Carriage ' |
| 10048 | 'Return |\n' |
| 10049 | ' ' |
| 10050 | '+-------------------------+-------------------------------+\n' |
| 10051 | ' | "\\r\\n" | Carriage Return + Line ' |
| 10052 | 'Feed |\n' |
| 10053 | ' ' |
| 10054 | '+-------------------------+-------------------------------+\n' |
| 10055 | ' | "\\v" or "\\x0b" | Line ' |
| 10056 | 'Tabulation |\n' |
| 10057 | ' ' |
| 10058 | '+-------------------------+-------------------------------+\n' |
| 10059 | ' | "\\f" or "\\x0c" | Form ' |
| 10060 | 'Feed |\n' |
| 10061 | ' ' |
| 10062 | '+-------------------------+-------------------------------+\n' |
| 10063 | ' | "\\x1c" | File ' |
| 10064 | 'Separator |\n' |
| 10065 | ' ' |
| 10066 | '+-------------------------+-------------------------------+\n' |
| 10067 | ' | "\\x1d" | Group ' |
| 10068 | 'Separator |\n' |
| 10069 | ' ' |
| 10070 | '+-------------------------+-------------------------------+\n' |
| 10071 | ' | "\\x1e" | Record ' |
| 10072 | 'Separator |\n' |
| 10073 | ' ' |
| 10074 | '+-------------------------+-------------------------------+\n' |
| 10075 | ' | "\\x85" | Next Line (C1 Control ' |
| 10076 | 'Code) |\n' |
| 10077 | ' ' |
| 10078 | '+-------------------------+-------------------------------+\n' |
| 10079 | ' | "\\u2028" | Line ' |
| 10080 | 'Separator |\n' |
| 10081 | ' ' |
| 10082 | '+-------------------------+-------------------------------+\n' |
| 10083 | ' | "\\u2029" | Paragraph ' |
| 10084 | 'Separator |\n' |
| 10085 | ' ' |
| 10086 | '+-------------------------+-------------------------------+\n' |
| 10087 | '\n' |
| 10088 | ' Changed in version 3.2: "\\v" and "\\f" added to list ' |
| 10089 | 'of line\n' |
| 10090 | ' boundaries.\n' |
| 10091 | '\n' |
| 10092 | ' For example:\n' |
| 10093 | '\n' |
| 10094 | " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" |
| 10095 | " ['ab c', '', 'de fg', 'kl']\n" |
| 10096 | " >>> 'ab c\\n\\nde " |
| 10097 | "fg\\rkl\\r\\n'.splitlines(keepends=True)\n" |
| 10098 | " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" |
| 10099 | '\n' |
| 10100 | ' Unlike "split()" when a delimiter string *sep* is ' |
| 10101 | 'given, this\n' |
| 10102 | ' method returns an empty list for the empty string, and ' |
| 10103 | 'a terminal\n' |
| 10104 | ' line break does not result in an extra line:\n' |
| 10105 | '\n' |
| 10106 | ' >>> "".splitlines()\n' |
| 10107 | ' []\n' |
| 10108 | ' >>> "One line\\n".splitlines()\n' |
| 10109 | " ['One line']\n" |
| 10110 | '\n' |
| 10111 | ' For comparison, "split(\'\\n\')" gives:\n' |
| 10112 | '\n' |
| 10113 | " >>> ''.split('\\n')\n" |
| 10114 | " ['']\n" |
| 10115 | " >>> 'Two lines\\n'.split('\\n')\n" |
| 10116 | " ['Two lines', '']\n" |
| 10117 | '\n' |
| 10118 | 'str.startswith(prefix[, start[, end]])\n' |
| 10119 | '\n' |
| 10120 | ' Return "True" if string starts with the *prefix*, ' |
| 10121 | 'otherwise return\n' |
| 10122 | ' "False". *prefix* can also be a tuple of prefixes to ' |
| 10123 | 'look for.\n' |
| 10124 | ' With optional *start*, test string beginning at that ' |
| 10125 | 'position.\n' |
| 10126 | ' With optional *end*, stop comparing string at that ' |
| 10127 | 'position.\n' |
| 10128 | '\n' |
| 10129 | 'str.strip([chars])\n' |
| 10130 | '\n' |
| 10131 | ' Return a copy of the string with the leading and ' |
| 10132 | 'trailing\n' |
| 10133 | ' characters removed. The *chars* argument is a string ' |
| 10134 | 'specifying the\n' |
| 10135 | ' set of characters to be removed. If omitted or "None", ' |
| 10136 | 'the *chars*\n' |
| 10137 | ' argument defaults to removing whitespace. The *chars* ' |
| 10138 | 'argument is\n' |
| 10139 | ' not a prefix or suffix; rather, all combinations of its ' |
| 10140 | 'values are\n' |
| 10141 | ' stripped:\n' |
| 10142 | '\n' |
| 10143 | " >>> ' spacious '.strip()\n" |
| 10144 | " 'spacious'\n" |
| 10145 | " >>> 'www.example.com'.strip('cmowz.')\n" |
| 10146 | " 'example'\n" |
| 10147 | '\n' |
| 10148 | ' The outermost leading and trailing *chars* argument ' |
| 10149 | 'values are\n' |
| 10150 | ' stripped from the string. Characters are removed from ' |
| 10151 | 'the leading\n' |
| 10152 | ' end until reaching a string character that is not ' |
| 10153 | 'contained in the\n' |
| 10154 | ' set of characters in *chars*. A similar action takes ' |
| 10155 | 'place on the\n' |
| 10156 | ' trailing end. For example:\n' |
| 10157 | '\n' |
| 10158 | " >>> comment_string = '#....... Section 3.2.1 Issue " |
| 10159 | "#32 .......'\n" |
| 10160 | " >>> comment_string.strip('.#! ')\n" |
| 10161 | " 'Section 3.2.1 Issue #32'\n" |
| 10162 | '\n' |
| 10163 | 'str.swapcase()\n' |
| 10164 | '\n' |
| 10165 | ' Return a copy of the string with uppercase characters ' |
| 10166 | 'converted to\n' |
| 10167 | ' lowercase and vice versa. Note that it is not ' |
| 10168 | 'necessarily true that\n' |
| 10169 | ' "s.swapcase().swapcase() == s".\n' |
| 10170 | '\n' |
| 10171 | 'str.title()\n' |
| 10172 | '\n' |
| 10173 | ' Return a titlecased version of the string where words ' |
| 10174 | 'start with an\n' |
| 10175 | ' uppercase character and the remaining characters are ' |
| 10176 | 'lowercase.\n' |
| 10177 | '\n' |
| 10178 | ' For example:\n' |
| 10179 | '\n' |
| 10180 | " >>> 'Hello world'.title()\n" |
| 10181 | " 'Hello World'\n" |
| 10182 | '\n' |
| 10183 | ' The algorithm uses a simple language-independent ' |
| 10184 | 'definition of a\n' |
| 10185 | ' word as groups of consecutive letters. The definition ' |
| 10186 | 'works in\n' |
| 10187 | ' many contexts but it means that apostrophes in ' |
| 10188 | 'contractions and\n' |
| 10189 | ' possessives form word boundaries, which may not be the ' |
| 10190 | 'desired\n' |
| 10191 | ' result:\n' |
| 10192 | '\n' |
| 10193 | ' >>> "they\'re bill\'s friends from the UK".title()\n' |
| 10194 | ' "They\'Re Bill\'S Friends From The Uk"\n' |
| 10195 | '\n' |
| 10196 | ' A workaround for apostrophes can be constructed using ' |
| 10197 | 'regular\n' |
| 10198 | ' expressions:\n' |
| 10199 | '\n' |
| 10200 | ' >>> import re\n' |
| 10201 | ' >>> def titlecase(s):\n' |
| 10202 | ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' |
| 10203 | ' ... lambda mo: ' |
| 10204 | 'mo.group(0)[0].upper() +\n' |
| 10205 | ' ... ' |
| 10206 | 'mo.group(0)[1:].lower(),\n' |
| 10207 | ' ... s)\n' |
| 10208 | ' ...\n' |
| 10209 | ' >>> titlecase("they\'re bill\'s friends.")\n' |
| 10210 | ' "They\'re Bill\'s Friends."\n' |
| 10211 | '\n' |
| 10212 | 'str.translate(table)\n' |
| 10213 | '\n' |
| 10214 | ' Return a copy of the string in which each character has ' |
| 10215 | 'been mapped\n' |
| 10216 | ' through the given translation table. The table must be ' |
| 10217 | 'an object\n' |
| 10218 | ' that implements indexing via "__getitem__()", typically ' |
| 10219 | 'a *mapping*\n' |
| 10220 | ' or *sequence*. When indexed by a Unicode ordinal (an ' |
| 10221 | 'integer), the\n' |
| 10222 | ' table object can do any of the following: return a ' |
| 10223 | 'Unicode ordinal\n' |
| 10224 | ' or a string, to map the character to one or more other ' |
| 10225 | 'characters;\n' |
| 10226 | ' return "None", to delete the character from the return ' |
| 10227 | 'string; or\n' |
| 10228 | ' raise a "LookupError" exception, to map the character ' |
| 10229 | 'to itself.\n' |
| 10230 | '\n' |
| 10231 | ' You can use "str.maketrans()" to create a translation ' |
| 10232 | 'map from\n' |
| 10233 | ' character-to-character mappings in different formats.\n' |
| 10234 | '\n' |
| 10235 | ' See also the "codecs" module for a more flexible ' |
| 10236 | 'approach to custom\n' |
| 10237 | ' character mappings.\n' |
| 10238 | '\n' |
| 10239 | 'str.upper()\n' |
| 10240 | '\n' |
| 10241 | ' Return a copy of the string with all the cased ' |
| 10242 | 'characters [4]\n' |
| 10243 | ' converted to uppercase. Note that ' |
| 10244 | '"str.upper().isupper()" might be\n' |
| 10245 | ' "False" if "s" contains uncased characters or if the ' |
| 10246 | 'Unicode\n' |
| 10247 | ' category of the resulting character(s) is not "Lu" ' |
| 10248 | '(Letter,\n' |
| 10249 | ' uppercase), but e.g. "Lt" (Letter, titlecase).\n' |
| 10250 | '\n' |
| 10251 | ' The uppercasing algorithm used is described in section ' |
| 10252 | '3.13 of the\n' |
| 10253 | ' Unicode Standard.\n' |
| 10254 | '\n' |
| 10255 | 'str.zfill(width)\n' |
| 10256 | '\n' |
| 10257 | ' Return a copy of the string left filled with ASCII ' |
| 10258 | '"\'0\'" digits to\n' |
| 10259 | ' make a string of length *width*. A leading sign prefix\n' |
| 10260 | ' ("\'+\'"/"\'-\'") is handled by inserting the padding ' |
| 10261 | '*after* the sign\n' |
| 10262 | ' character rather than before. The original string is ' |
| 10263 | 'returned if\n' |
| 10264 | ' *width* is less than or equal to "len(s)".\n' |
| 10265 | '\n' |
| 10266 | ' For example:\n' |
| 10267 | '\n' |
| 10268 | ' >>> "42".zfill(5)\n' |
| 10269 | " '00042'\n" |
| 10270 | ' >>> "-42".zfill(5)\n' |
| 10271 | " '-0042'\n", |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10272 | 'strings': 'String and Bytes literals\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10273 | '*************************\n' |
| 10274 | '\n' |
| 10275 | 'String literals are described by the following lexical ' |
| 10276 | 'definitions:\n' |
| 10277 | '\n' |
| 10278 | ' stringliteral ::= [stringprefix](shortstring | longstring)\n' |
| 10279 | ' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n' |
| 10280 | ' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | ' |
| 10281 | '"Rf" | "RF"\n' |
| 10282 | ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' ' |
| 10283 | 'shortstringitem* \'"\'\n' |
| 10284 | ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | ' |
| 10285 | '\'"""\' longstringitem* \'"""\'\n' |
| 10286 | ' shortstringitem ::= shortstringchar | stringescapeseq\n' |
| 10287 | ' longstringitem ::= longstringchar | stringescapeseq\n' |
| 10288 | ' shortstringchar ::= <any source character except "\\" or ' |
| 10289 | 'newline or the quote>\n' |
| 10290 | ' longstringchar ::= <any source character except "\\">\n' |
| 10291 | ' stringescapeseq ::= "\\" <any source character>\n' |
| 10292 | '\n' |
| 10293 | ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n' |
| 10294 | ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | ' |
| 10295 | '"rb" | "rB" | "Rb" | "RB"\n' |
| 10296 | ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' ' |
| 10297 | 'shortbytesitem* \'"\'\n' |
| 10298 | ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' ' |
| 10299 | 'longbytesitem* \'"""\'\n' |
| 10300 | ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n' |
| 10301 | ' longbytesitem ::= longbyteschar | bytesescapeseq\n' |
| 10302 | ' shortbyteschar ::= <any ASCII character except "\\" or newline ' |
| 10303 | 'or the quote>\n' |
| 10304 | ' longbyteschar ::= <any ASCII character except "\\">\n' |
| 10305 | ' bytesescapeseq ::= "\\" <any ASCII character>\n' |
| 10306 | '\n' |
| 10307 | 'One syntactic restriction not indicated by these productions is ' |
| 10308 | 'that\n' |
| 10309 | 'whitespace is not allowed between the "stringprefix" or ' |
| 10310 | '"bytesprefix"\n' |
| 10311 | 'and the rest of the literal. The source character set is defined ' |
| 10312 | 'by\n' |
| 10313 | 'the encoding declaration; it is UTF-8 if no encoding declaration ' |
| 10314 | 'is\n' |
| 10315 | 'given in the source file; see section Encoding declarations.\n' |
| 10316 | '\n' |
| 10317 | 'In plain English: Both types of literals can be enclosed in ' |
| 10318 | 'matching\n' |
| 10319 | 'single quotes ("\'") or double quotes ("""). They can also be ' |
| 10320 | 'enclosed\n' |
| 10321 | 'in matching groups of three single or double quotes (these are\n' |
| 10322 | 'generally referred to as *triple-quoted strings*). The ' |
| 10323 | 'backslash\n' |
| 10324 | '("\\") character is used to escape characters that otherwise have ' |
| 10325 | 'a\n' |
| 10326 | 'special meaning, such as newline, backslash itself, or the quote\n' |
| 10327 | 'character.\n' |
| 10328 | '\n' |
| 10329 | 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they ' |
| 10330 | 'produce\n' |
| 10331 | 'an instance of the "bytes" type instead of the "str" type. They ' |
| 10332 | 'may\n' |
| 10333 | 'only contain ASCII characters; bytes with a numeric value of 128 ' |
| 10334 | 'or\n' |
| 10335 | 'greater must be expressed with escapes.\n' |
| 10336 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10337 | 'Both string and bytes literals may optionally be prefixed with a\n' |
| 10338 | 'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* ' |
| 10339 | 'and treat\n' |
| 10340 | 'backslashes as literal characters. As a result, in string ' |
| 10341 | 'literals,\n' |
| 10342 | '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated ' |
| 10343 | 'specially.\n' |
| 10344 | "Given that Python 2.x's raw unicode literals behave differently " |
| 10345 | 'than\n' |
| 10346 | 'Python 3.x\'s the "\'ur\'" syntax is not supported.\n' |
| 10347 | '\n' |
| 10348 | 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has ' |
| 10349 | 'been\n' |
| 10350 | 'added as a synonym of "\'br\'".\n' |
| 10351 | '\n' |
| 10352 | 'New in version 3.3: Support for the unicode legacy literal\n' |
| 10353 | '("u\'value\'") was reintroduced to simplify the maintenance of ' |
| 10354 | 'dual\n' |
| 10355 | 'Python 2.x and 3.x codebases. See **PEP 414** for more ' |
| 10356 | 'information.\n' |
| 10357 | '\n' |
| 10358 | 'A string literal with "\'f\'" or "\'F\'" in its prefix is a ' |
| 10359 | '*formatted\n' |
| 10360 | 'string literal*; see Formatted string literals. The "\'f\'" may ' |
| 10361 | 'be\n' |
| 10362 | 'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore ' |
| 10363 | 'raw\n' |
| 10364 | 'formatted strings are possible, but formatted bytes literals are ' |
| 10365 | 'not.\n' |
| 10366 | '\n' |
| 10367 | 'In triple-quoted literals, unescaped newlines and quotes are ' |
| 10368 | 'allowed\n' |
| 10369 | '(and are retained), except that three unescaped quotes in a row\n' |
| 10370 | 'terminate the literal. (A "quote" is the character used to open ' |
| 10371 | 'the\n' |
| 10372 | 'literal, i.e. either "\'" or """.)\n' |
| 10373 | '\n' |
| 10374 | 'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences ' |
| 10375 | 'in string\n' |
| 10376 | 'and bytes literals are interpreted according to rules similar to ' |
| 10377 | 'those\n' |
| 10378 | 'used by Standard C. The recognized escape sequences are:\n' |
| 10379 | '\n' |
| 10380 | '+-------------------+-----------------------------------+---------+\n' |
| 10381 | '| Escape Sequence | Meaning | Notes ' |
| 10382 | '|\n' |
| 10383 | '+===================+===================================+=========+\n' |
| 10384 | '| "\\newline" | Backslash and newline ignored ' |
| 10385 | '| |\n' |
| 10386 | '+-------------------+-----------------------------------+---------+\n' |
| 10387 | '| "\\\\" | Backslash ("\\") ' |
| 10388 | '| |\n' |
| 10389 | '+-------------------+-----------------------------------+---------+\n' |
| 10390 | '| "\\\'" | Single quote ("\'") ' |
| 10391 | '| |\n' |
| 10392 | '+-------------------+-----------------------------------+---------+\n' |
| 10393 | '| "\\"" | Double quote (""") ' |
| 10394 | '| |\n' |
| 10395 | '+-------------------+-----------------------------------+---------+\n' |
| 10396 | '| "\\a" | ASCII Bell (BEL) ' |
| 10397 | '| |\n' |
| 10398 | '+-------------------+-----------------------------------+---------+\n' |
| 10399 | '| "\\b" | ASCII Backspace (BS) ' |
| 10400 | '| |\n' |
| 10401 | '+-------------------+-----------------------------------+---------+\n' |
| 10402 | '| "\\f" | ASCII Formfeed (FF) ' |
| 10403 | '| |\n' |
| 10404 | '+-------------------+-----------------------------------+---------+\n' |
| 10405 | '| "\\n" | ASCII Linefeed (LF) ' |
| 10406 | '| |\n' |
| 10407 | '+-------------------+-----------------------------------+---------+\n' |
| 10408 | '| "\\r" | ASCII Carriage Return (CR) ' |
| 10409 | '| |\n' |
| 10410 | '+-------------------+-----------------------------------+---------+\n' |
| 10411 | '| "\\t" | ASCII Horizontal Tab (TAB) ' |
| 10412 | '| |\n' |
| 10413 | '+-------------------+-----------------------------------+---------+\n' |
| 10414 | '| "\\v" | ASCII Vertical Tab (VT) ' |
| 10415 | '| |\n' |
| 10416 | '+-------------------+-----------------------------------+---------+\n' |
| 10417 | '| "\\ooo" | Character with octal value *ooo* | ' |
| 10418 | '(1,3) |\n' |
| 10419 | '+-------------------+-----------------------------------+---------+\n' |
| 10420 | '| "\\xhh" | Character with hex value *hh* | ' |
| 10421 | '(2,3) |\n' |
| 10422 | '+-------------------+-----------------------------------+---------+\n' |
| 10423 | '\n' |
| 10424 | 'Escape sequences only recognized in string literals are:\n' |
| 10425 | '\n' |
| 10426 | '+-------------------+-----------------------------------+---------+\n' |
| 10427 | '| Escape Sequence | Meaning | Notes ' |
| 10428 | '|\n' |
| 10429 | '+===================+===================================+=========+\n' |
| 10430 | '| "\\N{name}" | Character named *name* in the | ' |
| 10431 | '(4) |\n' |
| 10432 | '| | Unicode database | ' |
| 10433 | '|\n' |
| 10434 | '+-------------------+-----------------------------------+---------+\n' |
| 10435 | '| "\\uxxxx" | Character with 16-bit hex value | ' |
| 10436 | '(5) |\n' |
| 10437 | '| | *xxxx* | ' |
| 10438 | '|\n' |
| 10439 | '+-------------------+-----------------------------------+---------+\n' |
| 10440 | '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' |
| 10441 | '(6) |\n' |
| 10442 | '| | *xxxxxxxx* | ' |
| 10443 | '|\n' |
| 10444 | '+-------------------+-----------------------------------+---------+\n' |
| 10445 | '\n' |
| 10446 | 'Notes:\n' |
| 10447 | '\n' |
| 10448 | '1. As in Standard C, up to three octal digits are accepted.\n' |
| 10449 | '\n' |
| 10450 | '2. Unlike in Standard C, exactly two hex digits are required.\n' |
| 10451 | '\n' |
| 10452 | '3. In a bytes literal, hexadecimal and octal escapes denote the\n' |
| 10453 | ' byte with the given value. In a string literal, these escapes\n' |
| 10454 | ' denote a Unicode character with the given value.\n' |
| 10455 | '\n' |
| 10456 | '4. Changed in version 3.3: Support for name aliases [1] has been\n' |
| 10457 | ' added.\n' |
| 10458 | '\n' |
| 10459 | '5. Exactly four hex digits are required.\n' |
| 10460 | '\n' |
| 10461 | '6. Any Unicode character can be encoded this way. Exactly eight\n' |
| 10462 | ' hex digits are required.\n' |
| 10463 | '\n' |
| 10464 | 'Unlike Standard C, all unrecognized escape sequences are left in ' |
| 10465 | 'the\n' |
| 10466 | 'string unchanged, i.e., *the backslash is left in the result*. ' |
| 10467 | '(This\n' |
| 10468 | 'behavior is useful when debugging: if an escape sequence is ' |
| 10469 | 'mistyped,\n' |
| 10470 | 'the resulting output is more easily recognized as broken.) It is ' |
| 10471 | 'also\n' |
| 10472 | 'important to note that the escape sequences only recognized in ' |
| 10473 | 'string\n' |
| 10474 | 'literals fall into the category of unrecognized escapes for ' |
| 10475 | 'bytes\n' |
| 10476 | 'literals.\n' |
| 10477 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 10478 | ' Changed in version 3.6: Unrecognized escape sequences produce ' |
| 10479 | 'a\n' |
| 10480 | ' DeprecationWarning. In some future version of Python they ' |
| 10481 | 'will be\n' |
| 10482 | ' a SyntaxError.\n' |
| 10483 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10484 | 'Even in a raw literal, quotes can be escaped with a backslash, ' |
| 10485 | 'but the\n' |
| 10486 | 'backslash remains in the result; for example, "r"\\""" is a ' |
| 10487 | 'valid\n' |
| 10488 | 'string literal consisting of two characters: a backslash and a ' |
| 10489 | 'double\n' |
| 10490 | 'quote; "r"\\"" is not a valid string literal (even a raw string ' |
| 10491 | 'cannot\n' |
| 10492 | 'end in an odd number of backslashes). Specifically, *a raw ' |
| 10493 | 'literal\n' |
| 10494 | 'cannot end in a single backslash* (since the backslash would ' |
| 10495 | 'escape\n' |
| 10496 | 'the following quote character). Note also that a single ' |
| 10497 | 'backslash\n' |
| 10498 | 'followed by a newline is interpreted as those two characters as ' |
| 10499 | 'part\n' |
| 10500 | 'of the literal, *not* as a line continuation.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10501 | 'subscriptions': 'Subscriptions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10502 | '*************\n' |
| 10503 | '\n' |
| 10504 | 'A subscription selects an item of a sequence (string, tuple ' |
| 10505 | 'or list)\n' |
| 10506 | 'or mapping (dictionary) object:\n' |
| 10507 | '\n' |
| 10508 | ' subscription ::= primary "[" expression_list "]"\n' |
| 10509 | '\n' |
| 10510 | 'The primary must evaluate to an object that supports ' |
| 10511 | 'subscription\n' |
| 10512 | '(lists or dictionaries for example). User-defined objects ' |
| 10513 | 'can support\n' |
| 10514 | 'subscription by defining a "__getitem__()" method.\n' |
| 10515 | '\n' |
| 10516 | 'For built-in objects, there are two types of objects that ' |
| 10517 | 'support\n' |
| 10518 | 'subscription:\n' |
| 10519 | '\n' |
| 10520 | 'If the primary is a mapping, the expression list must ' |
| 10521 | 'evaluate to an\n' |
| 10522 | 'object whose value is one of the keys of the mapping, and ' |
| 10523 | 'the\n' |
| 10524 | 'subscription selects the value in the mapping that ' |
| 10525 | 'corresponds to that\n' |
| 10526 | 'key. (The expression list is a tuple except if it has ' |
| 10527 | 'exactly one\n' |
| 10528 | 'item.)\n' |
| 10529 | '\n' |
| 10530 | 'If the primary is a sequence, the expression (list) must ' |
| 10531 | 'evaluate to\n' |
| 10532 | 'an integer or a slice (as discussed in the following ' |
| 10533 | 'section).\n' |
| 10534 | '\n' |
| 10535 | 'The formal syntax makes no special provision for negative ' |
| 10536 | 'indices in\n' |
| 10537 | 'sequences; however, built-in sequences all provide a ' |
| 10538 | '"__getitem__()"\n' |
| 10539 | 'method that interprets negative indices by adding the ' |
| 10540 | 'length of the\n' |
| 10541 | 'sequence to the index (so that "x[-1]" selects the last ' |
| 10542 | 'item of "x").\n' |
| 10543 | 'The resulting value must be a nonnegative integer less than ' |
| 10544 | 'the number\n' |
| 10545 | 'of items in the sequence, and the subscription selects the ' |
| 10546 | 'item whose\n' |
| 10547 | 'index is that value (counting from zero). Since the support ' |
| 10548 | 'for\n' |
| 10549 | "negative indices and slicing occurs in the object's " |
| 10550 | '"__getitem__()"\n' |
| 10551 | 'method, subclasses overriding this method will need to ' |
| 10552 | 'explicitly add\n' |
| 10553 | 'that support.\n' |
| 10554 | '\n' |
| 10555 | "A string's items are characters. A character is not a " |
| 10556 | 'separate data\n' |
| 10557 | 'type but a string of exactly one character.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10558 | 'truth': 'Truth Value Testing\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10559 | '*******************\n' |
| 10560 | '\n' |
| 10561 | '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] | 10562 | '"while" condition or as operand of the Boolean operations below.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10563 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10564 | 'By default, an object is considered true unless its class defines\n' |
| 10565 | 'either a "__bool__()" method that returns "False" or a "__len__()"\n' |
| 10566 | 'method that returns zero, when called with the object. [1] Here ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10567 | 'are\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10568 | 'most of the built-in objects considered false:\n' |
| 10569 | '\n' |
| 10570 | '* constants defined to be false: "None" and "False".\n' |
| 10571 | '\n' |
| 10572 | '* zero of any numeric type: "0", "0.0", "0j", "Decimal(0)",\n' |
| 10573 | ' "Fraction(0, 1)"\n' |
| 10574 | '\n' |
| 10575 | '* empty sequences and collections: "\'\'", "()", "[]", "{}", ' |
| 10576 | '"set()",\n' |
| 10577 | ' "range(0)"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10578 | '\n' |
| 10579 | 'Operations and built-in functions that have a Boolean result ' |
| 10580 | 'always\n' |
| 10581 | 'return "0" or "False" for false and "1" or "True" for true, unless\n' |
| 10582 | 'otherwise stated. (Important exception: the Boolean operations ' |
| 10583 | '"or"\n' |
| 10584 | 'and "and" always return one of their operands.)\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10585 | 'try': 'The "try" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10586 | '*******************\n' |
| 10587 | '\n' |
| 10588 | 'The "try" statement specifies exception handlers and/or cleanup code\n' |
| 10589 | 'for a group of statements:\n' |
| 10590 | '\n' |
| 10591 | ' try_stmt ::= try1_stmt | try2_stmt\n' |
| 10592 | ' try1_stmt ::= "try" ":" suite\n' |
| 10593 | ' ("except" [expression ["as" identifier]] ":" ' |
| 10594 | 'suite)+\n' |
| 10595 | ' ["else" ":" suite]\n' |
| 10596 | ' ["finally" ":" suite]\n' |
| 10597 | ' try2_stmt ::= "try" ":" suite\n' |
| 10598 | ' "finally" ":" suite\n' |
| 10599 | '\n' |
| 10600 | 'The "except" clause(s) specify one or more exception handlers. When ' |
| 10601 | 'no\n' |
| 10602 | 'exception occurs in the "try" clause, no exception handler is\n' |
| 10603 | 'executed. When an exception occurs in the "try" suite, a search for ' |
| 10604 | 'an\n' |
| 10605 | 'exception handler is started. This search inspects the except ' |
| 10606 | 'clauses\n' |
| 10607 | 'in turn until one is found that matches the exception. An ' |
| 10608 | 'expression-\n' |
| 10609 | 'less except clause, if present, must be last; it matches any\n' |
| 10610 | 'exception. For an except clause with an expression, that expression\n' |
| 10611 | 'is evaluated, and the clause matches the exception if the resulting\n' |
| 10612 | 'object is "compatible" with the exception. An object is compatible\n' |
| 10613 | 'with an exception if it is the class or a base class of the ' |
| 10614 | 'exception\n' |
| 10615 | 'object or a tuple containing an item compatible with the exception.\n' |
| 10616 | '\n' |
| 10617 | 'If no except clause matches the exception, the search for an ' |
| 10618 | 'exception\n' |
| 10619 | 'handler continues in the surrounding code and on the invocation ' |
| 10620 | 'stack.\n' |
| 10621 | '[1]\n' |
| 10622 | '\n' |
| 10623 | 'If the evaluation of an expression in the header of an except clause\n' |
| 10624 | 'raises an exception, the original search for a handler is canceled ' |
| 10625 | 'and\n' |
| 10626 | 'a search starts for the new exception in the surrounding code and on\n' |
| 10627 | 'the call stack (it is treated as if the entire "try" statement ' |
| 10628 | 'raised\n' |
| 10629 | 'the exception).\n' |
| 10630 | '\n' |
| 10631 | 'When a matching except clause is found, the exception is assigned to\n' |
| 10632 | 'the target specified after the "as" keyword in that except clause, ' |
| 10633 | 'if\n' |
| 10634 | "present, and the except clause's suite is executed. All except\n" |
| 10635 | 'clauses must have an executable block. When the end of this block ' |
| 10636 | 'is\n' |
| 10637 | 'reached, execution continues normally after the entire try ' |
| 10638 | 'statement.\n' |
| 10639 | '(This means that if two nested handlers exist for the same ' |
| 10640 | 'exception,\n' |
| 10641 | 'and the exception occurs in the try clause of the inner handler, the\n' |
| 10642 | 'outer handler will not handle the exception.)\n' |
| 10643 | '\n' |
| 10644 | 'When an exception has been assigned using "as target", it is cleared\n' |
| 10645 | 'at the end of the except clause. This is as if\n' |
| 10646 | '\n' |
| 10647 | ' except E as N:\n' |
| 10648 | ' foo\n' |
| 10649 | '\n' |
| 10650 | 'was translated to\n' |
| 10651 | '\n' |
| 10652 | ' except E as N:\n' |
| 10653 | ' try:\n' |
| 10654 | ' foo\n' |
| 10655 | ' finally:\n' |
| 10656 | ' del N\n' |
| 10657 | '\n' |
| 10658 | 'This means the exception must be assigned to a different name to be\n' |
| 10659 | 'able to refer to it after the except clause. Exceptions are cleared\n' |
| 10660 | 'because with the traceback attached to them, they form a reference\n' |
| 10661 | 'cycle with the stack frame, keeping all locals in that frame alive\n' |
| 10662 | 'until the next garbage collection occurs.\n' |
| 10663 | '\n' |
| 10664 | "Before an except clause's suite is executed, details about the\n" |
| 10665 | 'exception are stored in the "sys" module and can be accessed via\n' |
| 10666 | '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' |
| 10667 | 'the\n' |
| 10668 | 'exception class, the exception instance and a traceback object (see\n' |
| 10669 | 'section The standard type hierarchy) identifying the point in the\n' |
| 10670 | 'program where the exception occurred. "sys.exc_info()" values are\n' |
| 10671 | 'restored to their previous values (before the call) when returning\n' |
| 10672 | 'from a function that handled an exception.\n' |
| 10673 | '\n' |
| 10674 | 'The optional "else" clause is executed if and when control flows off\n' |
| 10675 | 'the end of the "try" clause. [2] Exceptions in the "else" clause are\n' |
| 10676 | 'not handled by the preceding "except" clauses.\n' |
| 10677 | '\n' |
| 10678 | 'If "finally" is present, it specifies a \'cleanup\' handler. The ' |
| 10679 | '"try"\n' |
| 10680 | 'clause is executed, including any "except" and "else" clauses. If ' |
| 10681 | 'an\n' |
| 10682 | 'exception occurs in any of the clauses and is not handled, the\n' |
| 10683 | 'exception is temporarily saved. The "finally" clause is executed. ' |
| 10684 | 'If\n' |
| 10685 | 'there is a saved exception it is re-raised at the end of the ' |
| 10686 | '"finally"\n' |
| 10687 | 'clause. If the "finally" clause raises another exception, the saved\n' |
| 10688 | 'exception is set as the context of the new exception. If the ' |
| 10689 | '"finally"\n' |
| 10690 | 'clause executes a "return" or "break" statement, the saved exception\n' |
| 10691 | 'is discarded:\n' |
| 10692 | '\n' |
| 10693 | ' >>> def f():\n' |
| 10694 | ' ... try:\n' |
| 10695 | ' ... 1/0\n' |
| 10696 | ' ... finally:\n' |
| 10697 | ' ... return 42\n' |
| 10698 | ' ...\n' |
| 10699 | ' >>> f()\n' |
| 10700 | ' 42\n' |
| 10701 | '\n' |
| 10702 | 'The exception information is not available to the program during\n' |
| 10703 | 'execution of the "finally" clause.\n' |
| 10704 | '\n' |
| 10705 | 'When a "return", "break" or "continue" statement is executed in the\n' |
| 10706 | '"try" suite of a "try"..."finally" statement, the "finally" clause ' |
| 10707 | 'is\n' |
| 10708 | 'also executed \'on the way out.\' A "continue" statement is illegal ' |
| 10709 | 'in\n' |
| 10710 | 'the "finally" clause. (The reason is a problem with the current\n' |
| 10711 | 'implementation --- this restriction may be lifted in the future).\n' |
| 10712 | '\n' |
| 10713 | 'The return value of a function is determined by the last "return"\n' |
| 10714 | 'statement executed. Since the "finally" clause always executes, a\n' |
| 10715 | '"return" statement executed in the "finally" clause will always be ' |
| 10716 | 'the\n' |
| 10717 | 'last one executed:\n' |
| 10718 | '\n' |
| 10719 | ' >>> def foo():\n' |
| 10720 | ' ... try:\n' |
| 10721 | " ... return 'try'\n" |
| 10722 | ' ... finally:\n' |
| 10723 | " ... return 'finally'\n" |
| 10724 | ' ...\n' |
| 10725 | ' >>> foo()\n' |
| 10726 | " 'finally'\n" |
| 10727 | '\n' |
| 10728 | 'Additional information on exceptions can be found in section\n' |
| 10729 | 'Exceptions, and information on using the "raise" statement to ' |
| 10730 | 'generate\n' |
| 10731 | 'exceptions may be found in section The raise statement.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10732 | 'types': 'The standard type hierarchy\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10733 | '***************************\n' |
| 10734 | '\n' |
| 10735 | 'Below is a list of the types that are built into Python. ' |
| 10736 | 'Extension\n' |
| 10737 | 'modules (written in C, Java, or other languages, depending on the\n' |
| 10738 | 'implementation) can define additional types. Future versions of\n' |
| 10739 | 'Python may add types to the type hierarchy (e.g., rational ' |
| 10740 | 'numbers,\n' |
| 10741 | 'efficiently stored arrays of integers, etc.), although such ' |
| 10742 | 'additions\n' |
| 10743 | 'will often be provided via the standard library instead.\n' |
| 10744 | '\n' |
| 10745 | 'Some of the type descriptions below contain a paragraph listing\n' |
| 10746 | "'special attributes.' These are attributes that provide access to " |
| 10747 | 'the\n' |
| 10748 | 'implementation and are not intended for general use. Their ' |
| 10749 | 'definition\n' |
| 10750 | 'may change in the future.\n' |
| 10751 | '\n' |
| 10752 | 'None\n' |
| 10753 | ' This type has a single value. There is a single object with ' |
| 10754 | 'this\n' |
| 10755 | ' value. This object is accessed through the built-in name "None". ' |
| 10756 | 'It\n' |
| 10757 | ' is used to signify the absence of a value in many situations, ' |
| 10758 | 'e.g.,\n' |
| 10759 | " it is returned from functions that don't explicitly return\n" |
| 10760 | ' anything. Its truth value is false.\n' |
| 10761 | '\n' |
| 10762 | 'NotImplemented\n' |
| 10763 | ' This type has a single value. There is a single object with ' |
| 10764 | 'this\n' |
| 10765 | ' value. This object is accessed through the built-in name\n' |
| 10766 | ' "NotImplemented". Numeric methods and rich comparison methods\n' |
| 10767 | ' should return this value if they do not implement the operation ' |
| 10768 | 'for\n' |
| 10769 | ' the operands provided. (The interpreter will then try the\n' |
| 10770 | ' reflected operation, or some other fallback, depending on the\n' |
| 10771 | ' operator.) Its truth value is true.\n' |
| 10772 | '\n' |
| 10773 | ' See Implementing the arithmetic operations for more details.\n' |
| 10774 | '\n' |
| 10775 | 'Ellipsis\n' |
| 10776 | ' This type has a single value. There is a single object with ' |
| 10777 | 'this\n' |
| 10778 | ' value. This object is accessed through the literal "..." or the\n' |
| 10779 | ' built-in name "Ellipsis". Its truth value is true.\n' |
| 10780 | '\n' |
| 10781 | '"numbers.Number"\n' |
| 10782 | ' These are created by numeric literals and returned as results ' |
| 10783 | 'by\n' |
| 10784 | ' arithmetic operators and arithmetic built-in functions. ' |
| 10785 | 'Numeric\n' |
| 10786 | ' objects are immutable; once created their value never changes.\n' |
| 10787 | ' Python numbers are of course strongly related to mathematical\n' |
| 10788 | ' numbers, but subject to the limitations of numerical ' |
| 10789 | 'representation\n' |
| 10790 | ' in computers.\n' |
| 10791 | '\n' |
| 10792 | ' Python distinguishes between integers, floating point numbers, ' |
| 10793 | 'and\n' |
| 10794 | ' complex numbers:\n' |
| 10795 | '\n' |
| 10796 | ' "numbers.Integral"\n' |
| 10797 | ' These represent elements from the mathematical set of ' |
| 10798 | 'integers\n' |
| 10799 | ' (positive and negative).\n' |
| 10800 | '\n' |
| 10801 | ' There are two types of integers:\n' |
| 10802 | '\n' |
| 10803 | ' Integers ("int")\n' |
| 10804 | '\n' |
| 10805 | ' These represent numbers in an unlimited range, subject to\n' |
| 10806 | ' available (virtual) memory only. For the purpose of ' |
| 10807 | 'shift\n' |
| 10808 | ' and mask operations, a binary representation is assumed, ' |
| 10809 | 'and\n' |
| 10810 | " negative numbers are represented in a variant of 2's\n" |
| 10811 | ' complement which gives the illusion of an infinite string ' |
| 10812 | 'of\n' |
| 10813 | ' sign bits extending to the left.\n' |
| 10814 | '\n' |
| 10815 | ' Booleans ("bool")\n' |
| 10816 | ' These represent the truth values False and True. The two\n' |
| 10817 | ' objects representing the values "False" and "True" are ' |
| 10818 | 'the\n' |
| 10819 | ' only Boolean objects. The Boolean type is a subtype of ' |
| 10820 | 'the\n' |
| 10821 | ' integer type, and Boolean values behave like the values 0 ' |
| 10822 | 'and\n' |
| 10823 | ' 1, respectively, in almost all contexts, the exception ' |
| 10824 | 'being\n' |
| 10825 | ' that when converted to a string, the strings ""False"" or\n' |
| 10826 | ' ""True"" are returned, respectively.\n' |
| 10827 | '\n' |
| 10828 | ' The rules for integer representation are intended to give ' |
| 10829 | 'the\n' |
| 10830 | ' most meaningful interpretation of shift and mask operations\n' |
| 10831 | ' involving negative integers.\n' |
| 10832 | '\n' |
| 10833 | ' "numbers.Real" ("float")\n' |
| 10834 | ' These represent machine-level double precision floating ' |
| 10835 | 'point\n' |
| 10836 | ' numbers. You are at the mercy of the underlying machine\n' |
| 10837 | ' architecture (and C or Java implementation) for the accepted\n' |
| 10838 | ' range and handling of overflow. Python does not support ' |
| 10839 | 'single-\n' |
| 10840 | ' precision floating point numbers; the savings in processor ' |
| 10841 | 'and\n' |
| 10842 | ' memory usage that are usually the reason for using these are\n' |
| 10843 | ' dwarfed by the overhead of using objects in Python, so there ' |
| 10844 | 'is\n' |
| 10845 | ' no reason to complicate the language with two kinds of ' |
| 10846 | 'floating\n' |
| 10847 | ' point numbers.\n' |
| 10848 | '\n' |
| 10849 | ' "numbers.Complex" ("complex")\n' |
| 10850 | ' These represent complex numbers as a pair of machine-level\n' |
| 10851 | ' double precision floating point numbers. The same caveats ' |
| 10852 | 'apply\n' |
| 10853 | ' as for floating point numbers. The real and imaginary parts ' |
| 10854 | 'of a\n' |
| 10855 | ' complex number "z" can be retrieved through the read-only\n' |
| 10856 | ' attributes "z.real" and "z.imag".\n' |
| 10857 | '\n' |
| 10858 | 'Sequences\n' |
| 10859 | ' These represent finite ordered sets indexed by non-negative\n' |
| 10860 | ' numbers. The built-in function "len()" returns the number of ' |
| 10861 | 'items\n' |
| 10862 | ' of a sequence. When the length of a sequence is *n*, the index ' |
| 10863 | 'set\n' |
| 10864 | ' contains the numbers 0, 1, ..., *n*-1. Item *i* of sequence *a* ' |
| 10865 | 'is\n' |
| 10866 | ' selected by "a[i]".\n' |
| 10867 | '\n' |
| 10868 | ' Sequences also support slicing: "a[i:j]" selects all items with\n' |
| 10869 | ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n' |
| 10870 | ' expression, a slice is a sequence of the same type. This ' |
| 10871 | 'implies\n' |
| 10872 | ' that the index set is renumbered so that it starts at 0.\n' |
| 10873 | '\n' |
| 10874 | ' Some sequences also support "extended slicing" with a third ' |
| 10875 | '"step"\n' |
| 10876 | ' parameter: "a[i:j:k]" selects all items of *a* with index *x* ' |
| 10877 | 'where\n' |
| 10878 | ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n' |
| 10879 | '\n' |
| 10880 | ' Sequences are distinguished according to their mutability:\n' |
| 10881 | '\n' |
| 10882 | ' Immutable sequences\n' |
| 10883 | ' An object of an immutable sequence type cannot change once it ' |
| 10884 | 'is\n' |
| 10885 | ' created. (If the object contains references to other ' |
| 10886 | 'objects,\n' |
| 10887 | ' these other objects may be mutable and may be changed; ' |
| 10888 | 'however,\n' |
| 10889 | ' the collection of objects directly referenced by an ' |
| 10890 | 'immutable\n' |
| 10891 | ' object cannot change.)\n' |
| 10892 | '\n' |
| 10893 | ' The following types are immutable sequences:\n' |
| 10894 | '\n' |
| 10895 | ' Strings\n' |
| 10896 | ' A string is a sequence of values that represent Unicode ' |
| 10897 | 'code\n' |
| 10898 | ' points. All the code points in the range "U+0000 - ' |
| 10899 | 'U+10FFFF"\n' |
| 10900 | " can be represented in a string. Python doesn't have a " |
| 10901 | '"char"\n' |
| 10902 | ' type; instead, every code point in the string is ' |
| 10903 | 'represented\n' |
| 10904 | ' as a string object with length "1". The built-in ' |
| 10905 | 'function\n' |
| 10906 | ' "ord()" converts a code point from its string form to an\n' |
| 10907 | ' integer in the range "0 - 10FFFF"; "chr()" converts an\n' |
| 10908 | ' integer in the range "0 - 10FFFF" to the corresponding ' |
| 10909 | 'length\n' |
| 10910 | ' "1" string object. "str.encode()" can be used to convert ' |
| 10911 | 'a\n' |
| 10912 | ' "str" to "bytes" using the given text encoding, and\n' |
| 10913 | ' "bytes.decode()" can be used to achieve the opposite.\n' |
| 10914 | '\n' |
| 10915 | ' Tuples\n' |
| 10916 | ' The items of a tuple are arbitrary Python objects. Tuples ' |
| 10917 | 'of\n' |
| 10918 | ' two or more items are formed by comma-separated lists of\n' |
| 10919 | " expressions. A tuple of one item (a 'singleton') can be\n" |
| 10920 | ' formed by affixing a comma to an expression (an expression ' |
| 10921 | 'by\n' |
| 10922 | ' itself does not create a tuple, since parentheses must be\n' |
| 10923 | ' usable for grouping of expressions). An empty tuple can ' |
| 10924 | 'be\n' |
| 10925 | ' formed by an empty pair of parentheses.\n' |
| 10926 | '\n' |
| 10927 | ' Bytes\n' |
| 10928 | ' A bytes object is an immutable array. The items are ' |
| 10929 | '8-bit\n' |
| 10930 | ' bytes, represented by integers in the range 0 <= x < 256.\n' |
| 10931 | ' Bytes literals (like "b\'abc\'") and the built-in ' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10932 | '"bytes()"\n' |
| 10933 | ' constructor can be used to create bytes objects. Also, ' |
| 10934 | 'bytes\n' |
| 10935 | ' objects can be decoded to strings via the "decode()" ' |
| 10936 | 'method.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10937 | '\n' |
| 10938 | ' Mutable sequences\n' |
| 10939 | ' Mutable sequences can be changed after they are created. ' |
| 10940 | 'The\n' |
| 10941 | ' subscription and slicing notations can be used as the target ' |
| 10942 | 'of\n' |
| 10943 | ' assignment and "del" (delete) statements.\n' |
| 10944 | '\n' |
| 10945 | ' There are currently two intrinsic mutable sequence types:\n' |
| 10946 | '\n' |
| 10947 | ' Lists\n' |
| 10948 | ' The items of a list are arbitrary Python objects. Lists ' |
| 10949 | 'are\n' |
| 10950 | ' formed by placing a comma-separated list of expressions ' |
| 10951 | 'in\n' |
| 10952 | ' square brackets. (Note that there are no special cases ' |
| 10953 | 'needed\n' |
| 10954 | ' to form lists of length 0 or 1.)\n' |
| 10955 | '\n' |
| 10956 | ' Byte Arrays\n' |
| 10957 | ' A bytearray object is a mutable array. They are created ' |
| 10958 | 'by\n' |
| 10959 | ' the built-in "bytearray()" constructor. Aside from being\n' |
| 10960 | ' mutable (and hence unhashable), byte arrays otherwise ' |
| 10961 | 'provide\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 10962 | ' the same interface and functionality as immutable "bytes"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 10963 | ' objects.\n' |
| 10964 | '\n' |
| 10965 | ' The extension module "array" provides an additional example ' |
| 10966 | 'of a\n' |
| 10967 | ' mutable sequence type, as does the "collections" module.\n' |
| 10968 | '\n' |
| 10969 | 'Set types\n' |
| 10970 | ' These represent unordered, finite sets of unique, immutable\n' |
| 10971 | ' objects. As such, they cannot be indexed by any subscript. ' |
| 10972 | 'However,\n' |
| 10973 | ' they can be iterated over, and the built-in function "len()"\n' |
| 10974 | ' returns the number of items in a set. Common uses for sets are ' |
| 10975 | 'fast\n' |
| 10976 | ' membership testing, removing duplicates from a sequence, and\n' |
| 10977 | ' computing mathematical operations such as intersection, union,\n' |
| 10978 | ' difference, and symmetric difference.\n' |
| 10979 | '\n' |
| 10980 | ' For set elements, the same immutability rules apply as for\n' |
| 10981 | ' dictionary keys. Note that numeric types obey the normal rules ' |
| 10982 | 'for\n' |
| 10983 | ' numeric comparison: if two numbers compare equal (e.g., "1" and\n' |
| 10984 | ' "1.0"), only one of them can be contained in a set.\n' |
| 10985 | '\n' |
| 10986 | ' There are currently two intrinsic set types:\n' |
| 10987 | '\n' |
| 10988 | ' Sets\n' |
| 10989 | ' These represent a mutable set. They are created by the ' |
| 10990 | 'built-in\n' |
| 10991 | ' "set()" constructor and can be modified afterwards by ' |
| 10992 | 'several\n' |
| 10993 | ' methods, such as "add()".\n' |
| 10994 | '\n' |
| 10995 | ' Frozen sets\n' |
| 10996 | ' These represent an immutable set. They are created by the\n' |
| 10997 | ' built-in "frozenset()" constructor. As a frozenset is ' |
| 10998 | 'immutable\n' |
| 10999 | ' and *hashable*, it can be used again as an element of ' |
| 11000 | 'another\n' |
| 11001 | ' set, or as a dictionary key.\n' |
| 11002 | '\n' |
| 11003 | 'Mappings\n' |
| 11004 | ' These represent finite sets of objects indexed by arbitrary ' |
| 11005 | 'index\n' |
| 11006 | ' sets. The subscript notation "a[k]" selects the item indexed by ' |
| 11007 | '"k"\n' |
| 11008 | ' from the mapping "a"; this can be used in expressions and as ' |
| 11009 | 'the\n' |
| 11010 | ' target of assignments or "del" statements. The built-in ' |
| 11011 | 'function\n' |
| 11012 | ' "len()" returns the number of items in a mapping.\n' |
| 11013 | '\n' |
| 11014 | ' There is currently a single intrinsic mapping type:\n' |
| 11015 | '\n' |
| 11016 | ' Dictionaries\n' |
| 11017 | ' These represent finite sets of objects indexed by nearly\n' |
| 11018 | ' arbitrary values. The only types of values not acceptable ' |
| 11019 | 'as\n' |
| 11020 | ' keys are values containing lists or dictionaries or other\n' |
| 11021 | ' mutable types that are compared by value rather than by ' |
| 11022 | 'object\n' |
| 11023 | ' identity, the reason being that the efficient implementation ' |
| 11024 | 'of\n' |
| 11025 | " dictionaries requires a key's hash value to remain constant.\n" |
| 11026 | ' Numeric types used for keys obey the normal rules for ' |
| 11027 | 'numeric\n' |
| 11028 | ' comparison: if two numbers compare equal (e.g., "1" and ' |
| 11029 | '"1.0")\n' |
| 11030 | ' then they can be used interchangeably to index the same\n' |
| 11031 | ' dictionary entry.\n' |
| 11032 | '\n' |
| 11033 | ' Dictionaries are mutable; they can be created by the "{...}"\n' |
| 11034 | ' notation (see section Dictionary displays).\n' |
| 11035 | '\n' |
| 11036 | ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n' |
| 11037 | ' additional examples of mapping types, as does the ' |
| 11038 | '"collections"\n' |
| 11039 | ' module.\n' |
| 11040 | '\n' |
| 11041 | 'Callable types\n' |
| 11042 | ' These are the types to which the function call operation (see\n' |
| 11043 | ' section Calls) can be applied:\n' |
| 11044 | '\n' |
| 11045 | ' User-defined functions\n' |
| 11046 | ' A user-defined function object is created by a function\n' |
| 11047 | ' definition (see section Function definitions). It should be\n' |
| 11048 | ' called with an argument list containing the same number of ' |
| 11049 | 'items\n' |
| 11050 | " as the function's formal parameter list.\n" |
| 11051 | '\n' |
| 11052 | ' Special attributes:\n' |
| 11053 | '\n' |
| 11054 | ' ' |
| 11055 | '+---------------------------+---------------------------------+-------------+\n' |
| 11056 | ' | Attribute | Meaning ' |
| 11057 | '| |\n' |
| 11058 | ' ' |
| 11059 | '+===========================+=================================+=============+\n' |
| 11060 | ' | "__doc__" | The function\'s ' |
| 11061 | 'documentation | Writable |\n' |
| 11062 | ' | | string, or "None" if ' |
| 11063 | '| |\n' |
| 11064 | ' | | unavailable; not inherited by ' |
| 11065 | '| |\n' |
| 11066 | ' | | subclasses ' |
| 11067 | '| |\n' |
| 11068 | ' ' |
| 11069 | '+---------------------------+---------------------------------+-------------+\n' |
| 11070 | ' | "__name__" | The function\'s ' |
| 11071 | 'name | Writable |\n' |
| 11072 | ' ' |
| 11073 | '+---------------------------+---------------------------------+-------------+\n' |
| 11074 | ' | "__qualname__" | The function\'s *qualified ' |
| 11075 | 'name* | Writable |\n' |
| 11076 | ' | | New in version 3.3. ' |
| 11077 | '| |\n' |
| 11078 | ' ' |
| 11079 | '+---------------------------+---------------------------------+-------------+\n' |
| 11080 | ' | "__module__" | The name of the module the ' |
| 11081 | '| Writable |\n' |
| 11082 | ' | | function was defined in, or ' |
| 11083 | '| |\n' |
| 11084 | ' | | "None" if unavailable. ' |
| 11085 | '| |\n' |
| 11086 | ' ' |
| 11087 | '+---------------------------+---------------------------------+-------------+\n' |
| 11088 | ' | "__defaults__" | A tuple containing default ' |
| 11089 | '| Writable |\n' |
| 11090 | ' | | argument values for those ' |
| 11091 | '| |\n' |
| 11092 | ' | | arguments that have defaults, ' |
| 11093 | '| |\n' |
| 11094 | ' | | or "None" if no arguments have ' |
| 11095 | '| |\n' |
| 11096 | ' | | a default value ' |
| 11097 | '| |\n' |
| 11098 | ' ' |
| 11099 | '+---------------------------+---------------------------------+-------------+\n' |
| 11100 | ' | "__code__" | The code object representing ' |
| 11101 | '| Writable |\n' |
| 11102 | ' | | the compiled function body. ' |
| 11103 | '| |\n' |
| 11104 | ' ' |
| 11105 | '+---------------------------+---------------------------------+-------------+\n' |
| 11106 | ' | "__globals__" | A reference to the dictionary ' |
| 11107 | '| Read-only |\n' |
| 11108 | " | | that holds the function's " |
| 11109 | '| |\n' |
| 11110 | ' | | global variables --- the global ' |
| 11111 | '| |\n' |
| 11112 | ' | | namespace of the module in ' |
| 11113 | '| |\n' |
| 11114 | ' | | which the function was defined. ' |
| 11115 | '| |\n' |
| 11116 | ' ' |
| 11117 | '+---------------------------+---------------------------------+-------------+\n' |
| 11118 | ' | "__dict__" | The namespace supporting ' |
| 11119 | '| Writable |\n' |
| 11120 | ' | | arbitrary function attributes. ' |
| 11121 | '| |\n' |
| 11122 | ' ' |
| 11123 | '+---------------------------+---------------------------------+-------------+\n' |
| 11124 | ' | "__closure__" | "None" or a tuple of cells that ' |
| 11125 | '| Read-only |\n' |
| 11126 | ' | | contain bindings for the ' |
| 11127 | '| |\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11128 | " | | function's free variables. See " |
| 11129 | '| |\n' |
| 11130 | ' | | below for information on the ' |
| 11131 | '| |\n' |
| 11132 | ' | | "cell_contents" attribute. ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11133 | '| |\n' |
| 11134 | ' ' |
| 11135 | '+---------------------------+---------------------------------+-------------+\n' |
| 11136 | ' | "__annotations__" | A dict containing annotations ' |
| 11137 | '| Writable |\n' |
| 11138 | ' | | of parameters. The keys of the ' |
| 11139 | '| |\n' |
| 11140 | ' | | dict are the parameter names, ' |
| 11141 | '| |\n' |
| 11142 | ' | | and "\'return\'" for the ' |
| 11143 | 'return | |\n' |
| 11144 | ' | | annotation, if provided. ' |
| 11145 | '| |\n' |
| 11146 | ' ' |
| 11147 | '+---------------------------+---------------------------------+-------------+\n' |
| 11148 | ' | "__kwdefaults__" | A dict containing defaults for ' |
| 11149 | '| Writable |\n' |
| 11150 | ' | | keyword-only parameters. ' |
| 11151 | '| |\n' |
| 11152 | ' ' |
| 11153 | '+---------------------------+---------------------------------+-------------+\n' |
| 11154 | '\n' |
| 11155 | ' Most of the attributes labelled "Writable" check the type of ' |
| 11156 | 'the\n' |
| 11157 | ' assigned value.\n' |
| 11158 | '\n' |
| 11159 | ' Function objects also support getting and setting arbitrary\n' |
| 11160 | ' attributes, which can be used, for example, to attach ' |
| 11161 | 'metadata\n' |
| 11162 | ' to functions. Regular attribute dot-notation is used to get ' |
| 11163 | 'and\n' |
| 11164 | ' set such attributes. *Note that the current implementation ' |
| 11165 | 'only\n' |
| 11166 | ' supports function attributes on user-defined functions. ' |
| 11167 | 'Function\n' |
| 11168 | ' attributes on built-in functions may be supported in the\n' |
| 11169 | ' future.*\n' |
| 11170 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11171 | ' A cell object has the attribute "cell_contents". This can be\n' |
| 11172 | ' used to get the value of the cell, as well as set the value.\n' |
| 11173 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11174 | " Additional information about a function's definition can be\n" |
| 11175 | ' retrieved from its code object; see the description of ' |
| 11176 | 'internal\n' |
| 11177 | ' types below.\n' |
| 11178 | '\n' |
| 11179 | ' Instance methods\n' |
| 11180 | ' An instance method object combines a class, a class instance ' |
| 11181 | 'and\n' |
| 11182 | ' any callable object (normally a user-defined function).\n' |
| 11183 | '\n' |
| 11184 | ' Special read-only attributes: "__self__" is the class ' |
| 11185 | 'instance\n' |
| 11186 | ' object, "__func__" is the function object; "__doc__" is the\n' |
| 11187 | ' method\'s documentation (same as "__func__.__doc__"); ' |
| 11188 | '"__name__"\n' |
| 11189 | ' is the method name (same as "__func__.__name__"); ' |
| 11190 | '"__module__"\n' |
| 11191 | ' is the name of the module the method was defined in, or ' |
| 11192 | '"None"\n' |
| 11193 | ' if unavailable.\n' |
| 11194 | '\n' |
| 11195 | ' Methods also support accessing (but not setting) the ' |
| 11196 | 'arbitrary\n' |
| 11197 | ' function attributes on the underlying function object.\n' |
| 11198 | '\n' |
| 11199 | ' User-defined method objects may be created when getting an\n' |
| 11200 | ' attribute of a class (perhaps via an instance of that class), ' |
| 11201 | 'if\n' |
| 11202 | ' that attribute is a user-defined function object or a class\n' |
| 11203 | ' method object.\n' |
| 11204 | '\n' |
| 11205 | ' When an instance method object is created by retrieving a ' |
| 11206 | 'user-\n' |
| 11207 | ' defined function object from a class via one of its ' |
| 11208 | 'instances,\n' |
| 11209 | ' its "__self__" attribute is the instance, and the method ' |
| 11210 | 'object\n' |
| 11211 | ' is said to be bound. The new method\'s "__func__" attribute ' |
| 11212 | 'is\n' |
| 11213 | ' the original function object.\n' |
| 11214 | '\n' |
| 11215 | ' When a user-defined method object is created by retrieving\n' |
| 11216 | ' another method object from a class or instance, the behaviour ' |
| 11217 | 'is\n' |
| 11218 | ' the same as for a function object, except that the ' |
| 11219 | '"__func__"\n' |
| 11220 | ' attribute of the new instance is not the original method ' |
| 11221 | 'object\n' |
| 11222 | ' but its "__func__" attribute.\n' |
| 11223 | '\n' |
| 11224 | ' When an instance method object is created by retrieving a ' |
| 11225 | 'class\n' |
| 11226 | ' method object from a class or instance, its "__self__" ' |
| 11227 | 'attribute\n' |
| 11228 | ' is the class itself, and its "__func__" attribute is the\n' |
| 11229 | ' function object underlying the class method.\n' |
| 11230 | '\n' |
| 11231 | ' When an instance method object is called, the underlying\n' |
| 11232 | ' function ("__func__") is called, inserting the class ' |
| 11233 | 'instance\n' |
| 11234 | ' ("__self__") in front of the argument list. For instance, ' |
| 11235 | 'when\n' |
| 11236 | ' "C" is a class which contains a definition for a function ' |
| 11237 | '"f()",\n' |
| 11238 | ' and "x" is an instance of "C", calling "x.f(1)" is equivalent ' |
| 11239 | 'to\n' |
| 11240 | ' calling "C.f(x, 1)".\n' |
| 11241 | '\n' |
| 11242 | ' When an instance method object is derived from a class ' |
| 11243 | 'method\n' |
| 11244 | ' object, the "class instance" stored in "__self__" will ' |
| 11245 | 'actually\n' |
| 11246 | ' be the class itself, so that calling either "x.f(1)" or ' |
| 11247 | '"C.f(1)"\n' |
| 11248 | ' is equivalent to calling "f(C,1)" where "f" is the ' |
| 11249 | 'underlying\n' |
| 11250 | ' function.\n' |
| 11251 | '\n' |
| 11252 | ' Note that the transformation from function object to ' |
| 11253 | 'instance\n' |
| 11254 | ' method object happens each time the attribute is retrieved ' |
| 11255 | 'from\n' |
| 11256 | ' the instance. In some cases, a fruitful optimization is to\n' |
| 11257 | ' assign the attribute to a local variable and call that local\n' |
| 11258 | ' variable. Also notice that this transformation only happens ' |
| 11259 | 'for\n' |
| 11260 | ' user-defined functions; other callable objects (and all non-\n' |
| 11261 | ' callable objects) are retrieved without transformation. It ' |
| 11262 | 'is\n' |
| 11263 | ' also important to note that user-defined functions which are\n' |
| 11264 | ' attributes of a class instance are not converted to bound\n' |
| 11265 | ' methods; this *only* happens when the function is an ' |
| 11266 | 'attribute\n' |
| 11267 | ' of the class.\n' |
| 11268 | '\n' |
| 11269 | ' Generator functions\n' |
| 11270 | ' A function or method which uses the "yield" statement (see\n' |
| 11271 | ' section The yield statement) is called a *generator ' |
| 11272 | 'function*.\n' |
| 11273 | ' Such a function, when called, always returns an iterator ' |
| 11274 | 'object\n' |
| 11275 | ' which can be used to execute the body of the function: ' |
| 11276 | 'calling\n' |
| 11277 | ' the iterator\'s "iterator.__next__()" method will cause the\n' |
| 11278 | ' function to execute until it provides a value using the ' |
| 11279 | '"yield"\n' |
| 11280 | ' statement. When the function executes a "return" statement ' |
| 11281 | 'or\n' |
| 11282 | ' falls off the end, a "StopIteration" exception is raised and ' |
| 11283 | 'the\n' |
| 11284 | ' iterator will have reached the end of the set of values to ' |
| 11285 | 'be\n' |
| 11286 | ' returned.\n' |
| 11287 | '\n' |
| 11288 | ' Coroutine functions\n' |
| 11289 | ' A function or method which is defined using "async def" is\n' |
| 11290 | ' called a *coroutine function*. Such a function, when ' |
| 11291 | 'called,\n' |
| 11292 | ' returns a *coroutine* object. It may contain "await"\n' |
| 11293 | ' expressions, as well as "async with" and "async for" ' |
| 11294 | 'statements.\n' |
| 11295 | ' See also the Coroutine Objects section.\n' |
| 11296 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11297 | ' Asynchronous generator functions\n' |
| 11298 | ' A function or method which is defined using "async def" and\n' |
| 11299 | ' which uses the "yield" statement is called a *asynchronous\n' |
| 11300 | ' generator function*. Such a function, when called, returns ' |
| 11301 | 'an\n' |
| 11302 | ' asynchronous iterator object which can be used in an "async ' |
| 11303 | 'for"\n' |
| 11304 | ' statement to execute the body of the function.\n' |
| 11305 | '\n' |
| 11306 | ' Calling the asynchronous iterator\'s "aiterator.__anext__()"\n' |
| 11307 | ' method will return an *awaitable* which when awaited will\n' |
| 11308 | ' execute until it provides a value using the "yield" ' |
| 11309 | 'expression.\n' |
| 11310 | ' When the function executes an empty "return" statement or ' |
| 11311 | 'falls\n' |
| 11312 | ' off the end, a "StopAsyncIteration" exception is raised and ' |
| 11313 | 'the\n' |
| 11314 | ' asynchronous iterator will have reached the end of the set ' |
| 11315 | 'of\n' |
| 11316 | ' values to be yielded.\n' |
| 11317 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11318 | ' Built-in functions\n' |
| 11319 | ' A built-in function object is a wrapper around a C function.\n' |
| 11320 | ' Examples of built-in functions are "len()" and "math.sin()"\n' |
| 11321 | ' ("math" is a standard built-in module). The number and type ' |
| 11322 | 'of\n' |
| 11323 | ' the arguments are determined by the C function. Special ' |
| 11324 | 'read-\n' |
| 11325 | ' only attributes: "__doc__" is the function\'s documentation\n' |
| 11326 | ' string, or "None" if unavailable; "__name__" is the ' |
| 11327 | "function's\n" |
| 11328 | ' name; "__self__" is set to "None" (but see the next item);\n' |
| 11329 | ' "__module__" is the name of the module the function was ' |
| 11330 | 'defined\n' |
| 11331 | ' in or "None" if unavailable.\n' |
| 11332 | '\n' |
| 11333 | ' Built-in methods\n' |
| 11334 | ' This is really a different disguise of a built-in function, ' |
| 11335 | 'this\n' |
| 11336 | ' time containing an object passed to the C function as an\n' |
| 11337 | ' implicit extra argument. An example of a built-in method is\n' |
| 11338 | ' "alist.append()", assuming *alist* is a list object. In this\n' |
| 11339 | ' case, the special read-only attribute "__self__" is set to ' |
| 11340 | 'the\n' |
| 11341 | ' object denoted by *alist*.\n' |
| 11342 | '\n' |
| 11343 | ' Classes\n' |
| 11344 | ' Classes are callable. These objects normally act as ' |
| 11345 | 'factories\n' |
| 11346 | ' for new instances of themselves, but variations are possible ' |
| 11347 | 'for\n' |
| 11348 | ' class types that override "__new__()". The arguments of the\n' |
| 11349 | ' call are passed to "__new__()" and, in the typical case, to\n' |
| 11350 | ' "__init__()" to initialize the new instance.\n' |
| 11351 | '\n' |
| 11352 | ' Class Instances\n' |
| 11353 | ' Instances of arbitrary classes can be made callable by ' |
| 11354 | 'defining\n' |
| 11355 | ' a "__call__()" method in their class.\n' |
| 11356 | '\n' |
| 11357 | 'Modules\n' |
| 11358 | ' Modules are a basic organizational unit of Python code, and are\n' |
| 11359 | ' created by the import system as invoked either by the "import"\n' |
| 11360 | ' statement (see "import"), or by calling functions such as\n' |
| 11361 | ' "importlib.import_module()" and built-in "__import__()". A ' |
| 11362 | 'module\n' |
| 11363 | ' object has a namespace implemented by a dictionary object (this ' |
| 11364 | 'is\n' |
| 11365 | ' the dictionary referenced by the "__globals__" attribute of\n' |
| 11366 | ' functions defined in the module). Attribute references are\n' |
| 11367 | ' translated to lookups in this dictionary, e.g., "m.x" is ' |
| 11368 | 'equivalent\n' |
| 11369 | ' to "m.__dict__["x"]". A module object does not contain the code\n' |
| 11370 | " object used to initialize the module (since it isn't needed " |
| 11371 | 'once\n' |
| 11372 | ' the initialization is done).\n' |
| 11373 | '\n' |
| 11374 | " Attribute assignment updates the module's namespace dictionary,\n" |
| 11375 | ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n' |
| 11376 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 11377 | ' Predefined (writable) attributes: "__name__" is the module\'s ' |
| 11378 | 'name;\n' |
| 11379 | ' "__doc__" is the module\'s documentation string, or "None" if\n' |
| 11380 | ' unavailable; "__annotations__" (optional) is a dictionary\n' |
| 11381 | ' containing *variable annotations* collected during module body\n' |
| 11382 | ' execution; "__file__" is the pathname of the file from which ' |
| 11383 | 'the\n' |
| 11384 | ' module was loaded, if it was loaded from a file. The "__file__"\n' |
| 11385 | ' attribute may be missing for certain types of modules, such as ' |
| 11386 | 'C\n' |
| 11387 | ' modules that are statically linked into the interpreter; for\n' |
| 11388 | ' extension modules loaded dynamically from a shared library, it ' |
| 11389 | 'is\n' |
| 11390 | ' the pathname of the shared library file.\n' |
| 11391 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11392 | ' Special read-only attribute: "__dict__" is the module\'s ' |
| 11393 | 'namespace\n' |
| 11394 | ' as a dictionary object.\n' |
| 11395 | '\n' |
| 11396 | ' **CPython implementation detail:** Because of the way CPython\n' |
| 11397 | ' clears module dictionaries, the module dictionary will be ' |
| 11398 | 'cleared\n' |
| 11399 | ' when the module falls out of scope even if the dictionary still ' |
| 11400 | 'has\n' |
| 11401 | ' live references. To avoid this, copy the dictionary or keep ' |
| 11402 | 'the\n' |
| 11403 | ' module around while using its dictionary directly.\n' |
| 11404 | '\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11405 | 'Custom classes\n' |
| 11406 | ' Custom class types are typically created by class definitions ' |
| 11407 | '(see\n' |
| 11408 | ' section Class definitions). A class has a namespace implemented ' |
| 11409 | 'by\n' |
| 11410 | ' a dictionary object. Class attribute references are translated ' |
| 11411 | 'to\n' |
| 11412 | ' lookups in this dictionary, e.g., "C.x" is translated to\n' |
| 11413 | ' "C.__dict__["x"]" (although there are a number of hooks which ' |
| 11414 | 'allow\n' |
| 11415 | ' for other means of locating attributes). When the attribute name ' |
| 11416 | 'is\n' |
| 11417 | ' not found there, the attribute search continues in the base\n' |
| 11418 | ' classes. This search of the base classes uses the C3 method\n' |
| 11419 | ' resolution order which behaves correctly even in the presence ' |
| 11420 | 'of\n' |
| 11421 | " 'diamond' inheritance structures where there are multiple\n" |
| 11422 | ' inheritance paths leading back to a common ancestor. Additional\n' |
| 11423 | ' details on the C3 MRO used by Python can be found in the\n' |
| 11424 | ' documentation accompanying the 2.3 release at\n' |
| 11425 | ' https://www.python.org/download/releases/2.3/mro/.\n' |
| 11426 | '\n' |
| 11427 | ' When a class attribute reference (for class "C", say) would ' |
| 11428 | 'yield a\n' |
| 11429 | ' class method object, it is transformed into an instance method\n' |
| 11430 | ' object whose "__self__" attributes is "C". When it would yield ' |
| 11431 | 'a\n' |
| 11432 | ' static method object, it is transformed into the object wrapped ' |
| 11433 | 'by\n' |
| 11434 | ' the static method object. See section Implementing Descriptors ' |
| 11435 | 'for\n' |
| 11436 | ' another way in which attributes retrieved from a class may ' |
| 11437 | 'differ\n' |
| 11438 | ' from those actually contained in its "__dict__".\n' |
| 11439 | '\n' |
| 11440 | " Class attribute assignments update the class's dictionary, " |
| 11441 | 'never\n' |
| 11442 | ' the dictionary of a base class.\n' |
| 11443 | '\n' |
| 11444 | ' A class object can be called (see above) to yield a class ' |
| 11445 | 'instance\n' |
| 11446 | ' (see below).\n' |
| 11447 | '\n' |
| 11448 | ' Special attributes: "__name__" is the class name; "__module__" ' |
| 11449 | 'is\n' |
| 11450 | ' the module name in which the class was defined; "__dict__" is ' |
| 11451 | 'the\n' |
| 11452 | ' dictionary containing the class\'s namespace; "__bases__" is a ' |
| 11453 | 'tuple\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11454 | ' containing the base classes, in the order of their occurrence ' |
| 11455 | 'in\n' |
| 11456 | ' the base class list; "__doc__" is the class\'s documentation ' |
| 11457 | 'string,\n' |
| 11458 | ' or "None" if undefined; "__annotations__" (optional) is a\n' |
| 11459 | ' dictionary containing *variable annotations* collected during ' |
| 11460 | 'class\n' |
| 11461 | ' body execution.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11462 | '\n' |
| 11463 | 'Class instances\n' |
| 11464 | ' A class instance is created by calling a class object (see ' |
| 11465 | 'above).\n' |
| 11466 | ' A class instance has a namespace implemented as a dictionary ' |
| 11467 | 'which\n' |
| 11468 | ' is the first place in which attribute references are searched.\n' |
| 11469 | " When an attribute is not found there, and the instance's class " |
| 11470 | 'has\n' |
| 11471 | ' an attribute by that name, the search continues with the class\n' |
| 11472 | ' attributes. If a class attribute is found that is a ' |
| 11473 | 'user-defined\n' |
| 11474 | ' function object, it is transformed into an instance method ' |
| 11475 | 'object\n' |
| 11476 | ' whose "__self__" attribute is the instance. Static method and\n' |
| 11477 | ' class method objects are also transformed; see above under\n' |
| 11478 | ' "Classes". See section Implementing Descriptors for another way ' |
| 11479 | 'in\n' |
| 11480 | ' which attributes of a class retrieved via its instances may ' |
| 11481 | 'differ\n' |
| 11482 | ' from the objects actually stored in the class\'s "__dict__". If ' |
| 11483 | 'no\n' |
| 11484 | " class attribute is found, and the object's class has a\n" |
| 11485 | ' "__getattr__()" method, that is called to satisfy the lookup.\n' |
| 11486 | '\n' |
| 11487 | " Attribute assignments and deletions update the instance's\n" |
| 11488 | " dictionary, never a class's dictionary. If the class has a\n" |
| 11489 | ' "__setattr__()" or "__delattr__()" method, this is called ' |
| 11490 | 'instead\n' |
| 11491 | ' of updating the instance dictionary directly.\n' |
| 11492 | '\n' |
| 11493 | ' Class instances can pretend to be numbers, sequences, or ' |
| 11494 | 'mappings\n' |
| 11495 | ' if they have methods with certain special names. See section\n' |
| 11496 | ' Special method names.\n' |
| 11497 | '\n' |
| 11498 | ' Special attributes: "__dict__" is the attribute dictionary;\n' |
| 11499 | ' "__class__" is the instance\'s class.\n' |
| 11500 | '\n' |
| 11501 | 'I/O objects (also known as file objects)\n' |
| 11502 | ' A *file object* represents an open file. Various shortcuts are\n' |
| 11503 | ' available to create file objects: the "open()" built-in ' |
| 11504 | 'function,\n' |
| 11505 | ' and also "os.popen()", "os.fdopen()", and the "makefile()" ' |
| 11506 | 'method\n' |
| 11507 | ' of socket objects (and perhaps by other functions or methods\n' |
| 11508 | ' provided by extension modules).\n' |
| 11509 | '\n' |
| 11510 | ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n' |
| 11511 | " initialized to file objects corresponding to the interpreter's\n" |
| 11512 | ' standard input, output and error streams; they are all open in ' |
| 11513 | 'text\n' |
| 11514 | ' mode and therefore follow the interface defined by the\n' |
| 11515 | ' "io.TextIOBase" abstract class.\n' |
| 11516 | '\n' |
| 11517 | 'Internal types\n' |
| 11518 | ' A few types used internally by the interpreter are exposed to ' |
| 11519 | 'the\n' |
| 11520 | ' user. Their definitions may change with future versions of the\n' |
| 11521 | ' interpreter, but they are mentioned here for completeness.\n' |
| 11522 | '\n' |
| 11523 | ' Code objects\n' |
| 11524 | ' Code objects represent *byte-compiled* executable Python ' |
| 11525 | 'code,\n' |
| 11526 | ' or *bytecode*. The difference between a code object and a\n' |
| 11527 | ' function object is that the function object contains an ' |
| 11528 | 'explicit\n' |
| 11529 | " reference to the function's globals (the module in which it " |
| 11530 | 'was\n' |
| 11531 | ' defined), while a code object contains no context; also the\n' |
| 11532 | ' default argument values are stored in the function object, ' |
| 11533 | 'not\n' |
| 11534 | ' in the code object (because they represent values calculated ' |
| 11535 | 'at\n' |
| 11536 | ' run-time). Unlike function objects, code objects are ' |
| 11537 | 'immutable\n' |
| 11538 | ' and contain no references (directly or indirectly) to ' |
| 11539 | 'mutable\n' |
| 11540 | ' objects.\n' |
| 11541 | '\n' |
| 11542 | ' Special read-only attributes: "co_name" gives the function ' |
| 11543 | 'name;\n' |
| 11544 | ' "co_argcount" is the number of positional arguments ' |
| 11545 | '(including\n' |
| 11546 | ' arguments with default values); "co_nlocals" is the number ' |
| 11547 | 'of\n' |
| 11548 | ' local variables used by the function (including arguments);\n' |
| 11549 | ' "co_varnames" is a tuple containing the names of the local\n' |
| 11550 | ' variables (starting with the argument names); "co_cellvars" ' |
| 11551 | 'is a\n' |
| 11552 | ' tuple containing the names of local variables that are\n' |
| 11553 | ' referenced by nested functions; "co_freevars" is a tuple\n' |
| 11554 | ' containing the names of free variables; "co_code" is a ' |
| 11555 | 'string\n' |
| 11556 | ' representing the sequence of bytecode instructions; ' |
| 11557 | '"co_consts"\n' |
| 11558 | ' is a tuple containing the literals used by the bytecode;\n' |
| 11559 | ' "co_names" is a tuple containing the names used by the ' |
| 11560 | 'bytecode;\n' |
| 11561 | ' "co_filename" is the filename from which the code was ' |
| 11562 | 'compiled;\n' |
| 11563 | ' "co_firstlineno" is the first line number of the function;\n' |
| 11564 | ' "co_lnotab" is a string encoding the mapping from bytecode\n' |
| 11565 | ' offsets to line numbers (for details see the source code of ' |
| 11566 | 'the\n' |
| 11567 | ' interpreter); "co_stacksize" is the required stack size\n' |
| 11568 | ' (including local variables); "co_flags" is an integer ' |
| 11569 | 'encoding a\n' |
| 11570 | ' number of flags for the interpreter.\n' |
| 11571 | '\n' |
| 11572 | ' The following flag bits are defined for "co_flags": bit ' |
| 11573 | '"0x04"\n' |
| 11574 | ' is set if the function uses the "*arguments" syntax to accept ' |
| 11575 | 'an\n' |
| 11576 | ' arbitrary number of positional arguments; bit "0x08" is set ' |
| 11577 | 'if\n' |
| 11578 | ' the function uses the "**keywords" syntax to accept ' |
| 11579 | 'arbitrary\n' |
| 11580 | ' keyword arguments; bit "0x20" is set if the function is a\n' |
| 11581 | ' generator.\n' |
| 11582 | '\n' |
| 11583 | ' Future feature declarations ("from __future__ import ' |
| 11584 | 'division")\n' |
| 11585 | ' also use bits in "co_flags" to indicate whether a code ' |
| 11586 | 'object\n' |
| 11587 | ' was compiled with a particular feature enabled: bit "0x2000" ' |
| 11588 | 'is\n' |
| 11589 | ' set if the function was compiled with future division ' |
| 11590 | 'enabled;\n' |
| 11591 | ' bits "0x10" and "0x1000" were used in earlier versions of\n' |
| 11592 | ' Python.\n' |
| 11593 | '\n' |
| 11594 | ' Other bits in "co_flags" are reserved for internal use.\n' |
| 11595 | '\n' |
| 11596 | ' If a code object represents a function, the first item in\n' |
| 11597 | ' "co_consts" is the documentation string of the function, or\n' |
| 11598 | ' "None" if undefined.\n' |
| 11599 | '\n' |
| 11600 | ' Frame objects\n' |
| 11601 | ' Frame objects represent execution frames. They may occur in\n' |
| 11602 | ' traceback objects (see below).\n' |
| 11603 | '\n' |
| 11604 | ' Special read-only attributes: "f_back" is to the previous ' |
| 11605 | 'stack\n' |
| 11606 | ' frame (towards the caller), or "None" if this is the bottom\n' |
| 11607 | ' stack frame; "f_code" is the code object being executed in ' |
| 11608 | 'this\n' |
| 11609 | ' frame; "f_locals" is the dictionary used to look up local\n' |
| 11610 | ' variables; "f_globals" is used for global variables;\n' |
| 11611 | ' "f_builtins" is used for built-in (intrinsic) names; ' |
| 11612 | '"f_lasti"\n' |
| 11613 | ' gives the precise instruction (this is an index into the\n' |
| 11614 | ' bytecode string of the code object).\n' |
| 11615 | '\n' |
| 11616 | ' Special writable attributes: "f_trace", if not "None", is a\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11617 | ' function called for various events during code execution ' |
| 11618 | '(this\n' |
| 11619 | ' is used by the debugger). Normally an event is triggered for\n' |
| 11620 | ' each new source line - this can be disabled by setting\n' |
| 11621 | ' "f_trace_lines" to "False".\n' |
| 11622 | '\n' |
| 11623 | ' Implementations *may* allow per-opcode events to be requested ' |
| 11624 | 'by\n' |
| 11625 | ' setting "f_trace_opcodes" to "True". Note that this may lead ' |
| 11626 | 'to\n' |
| 11627 | ' undefined interpreter behaviour if exceptions raised by the\n' |
| 11628 | ' trace function escape to the function being traced.\n' |
| 11629 | '\n' |
| 11630 | ' "f_lineno" is the current line number of the frame --- ' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11631 | 'writing\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11632 | ' to this from within a trace function jumps to the given line\n' |
| 11633 | ' (only for the bottom-most frame). A debugger can implement ' |
| 11634 | 'a\n' |
| 11635 | ' Jump command (aka Set Next Statement) by writing to ' |
| 11636 | 'f_lineno.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11637 | '\n' |
| 11638 | ' Frame objects support one method:\n' |
| 11639 | '\n' |
| 11640 | ' frame.clear()\n' |
| 11641 | '\n' |
| 11642 | ' This method clears all references to local variables held ' |
| 11643 | 'by\n' |
| 11644 | ' the frame. Also, if the frame belonged to a generator, ' |
| 11645 | 'the\n' |
| 11646 | ' generator is finalized. This helps break reference ' |
| 11647 | 'cycles\n' |
| 11648 | ' involving frame objects (for example when catching an\n' |
| 11649 | ' exception and storing its traceback for later use).\n' |
| 11650 | '\n' |
| 11651 | ' "RuntimeError" is raised if the frame is currently ' |
| 11652 | 'executing.\n' |
| 11653 | '\n' |
| 11654 | ' New in version 3.4.\n' |
| 11655 | '\n' |
| 11656 | ' Traceback objects\n' |
| 11657 | ' Traceback objects represent a stack trace of an exception. ' |
| 11658 | 'A\n' |
| 11659 | ' traceback object is created when an exception occurs. When ' |
| 11660 | 'the\n' |
| 11661 | ' search for an exception handler unwinds the execution stack, ' |
| 11662 | 'at\n' |
| 11663 | ' each unwound level a traceback object is inserted in front ' |
| 11664 | 'of\n' |
| 11665 | ' the current traceback. When an exception handler is ' |
| 11666 | 'entered,\n' |
| 11667 | ' the stack trace is made available to the program. (See ' |
| 11668 | 'section\n' |
| 11669 | ' The try statement.) It is accessible as the third item of ' |
| 11670 | 'the\n' |
| 11671 | ' tuple returned by "sys.exc_info()". When the program contains ' |
| 11672 | 'no\n' |
| 11673 | ' suitable handler, the stack trace is written (nicely ' |
| 11674 | 'formatted)\n' |
| 11675 | ' to the standard error stream; if the interpreter is ' |
| 11676 | 'interactive,\n' |
| 11677 | ' it is also made available to the user as ' |
| 11678 | '"sys.last_traceback".\n' |
| 11679 | '\n' |
| 11680 | ' Special read-only attributes: "tb_next" is the next level in ' |
| 11681 | 'the\n' |
| 11682 | ' stack trace (towards the frame where the exception occurred), ' |
| 11683 | 'or\n' |
| 11684 | ' "None" if there is no next level; "tb_frame" points to the\n' |
| 11685 | ' execution frame of the current level; "tb_lineno" gives the ' |
| 11686 | 'line\n' |
| 11687 | ' number where the exception occurred; "tb_lasti" indicates ' |
| 11688 | 'the\n' |
| 11689 | ' precise instruction. The line number and last instruction ' |
| 11690 | 'in\n' |
| 11691 | ' the traceback may differ from the line number of its frame\n' |
| 11692 | ' object if the exception occurred in a "try" statement with ' |
| 11693 | 'no\n' |
| 11694 | ' matching except clause or with a finally clause.\n' |
| 11695 | '\n' |
| 11696 | ' Slice objects\n' |
| 11697 | ' Slice objects are used to represent slices for ' |
| 11698 | '"__getitem__()"\n' |
| 11699 | ' methods. They are also created by the built-in "slice()"\n' |
| 11700 | ' function.\n' |
| 11701 | '\n' |
| 11702 | ' Special read-only attributes: "start" is the lower bound; ' |
| 11703 | '"stop"\n' |
| 11704 | ' is the upper bound; "step" is the step value; each is "None" ' |
| 11705 | 'if\n' |
| 11706 | ' omitted. These attributes can have any type.\n' |
| 11707 | '\n' |
| 11708 | ' Slice objects support one method:\n' |
| 11709 | '\n' |
| 11710 | ' slice.indices(self, length)\n' |
| 11711 | '\n' |
| 11712 | ' This method takes a single integer argument *length* and\n' |
| 11713 | ' computes information about the slice that the slice ' |
| 11714 | 'object\n' |
| 11715 | ' would describe if applied to a sequence of *length* ' |
| 11716 | 'items.\n' |
| 11717 | ' It returns a tuple of three integers; respectively these ' |
| 11718 | 'are\n' |
| 11719 | ' the *start* and *stop* indices and the *step* or stride\n' |
| 11720 | ' length of the slice. Missing or out-of-bounds indices are\n' |
| 11721 | ' handled in a manner consistent with regular slices.\n' |
| 11722 | '\n' |
| 11723 | ' Static method objects\n' |
| 11724 | ' Static method objects provide a way of defeating the\n' |
| 11725 | ' transformation of function objects to method objects ' |
| 11726 | 'described\n' |
| 11727 | ' above. A static method object is a wrapper around any other\n' |
| 11728 | ' object, usually a user-defined method object. When a static\n' |
| 11729 | ' method object is retrieved from a class or a class instance, ' |
| 11730 | 'the\n' |
| 11731 | ' object actually returned is the wrapped object, which is not\n' |
| 11732 | ' subject to any further transformation. Static method objects ' |
| 11733 | 'are\n' |
| 11734 | ' not themselves callable, although the objects they wrap ' |
| 11735 | 'usually\n' |
| 11736 | ' are. Static method objects are created by the built-in\n' |
| 11737 | ' "staticmethod()" constructor.\n' |
| 11738 | '\n' |
| 11739 | ' Class method objects\n' |
| 11740 | ' A class method object, like a static method object, is a ' |
| 11741 | 'wrapper\n' |
| 11742 | ' around another object that alters the way in which that ' |
| 11743 | 'object\n' |
| 11744 | ' is retrieved from classes and class instances. The behaviour ' |
| 11745 | 'of\n' |
| 11746 | ' class method objects upon such retrieval is described above,\n' |
| 11747 | ' under "User-defined methods". Class method objects are ' |
| 11748 | 'created\n' |
| 11749 | ' by the built-in "classmethod()" constructor.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11750 | 'typesfunctions': 'Functions\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11751 | '*********\n' |
| 11752 | '\n' |
| 11753 | 'Function objects are created by function definitions. The ' |
| 11754 | 'only\n' |
| 11755 | 'operation on a function object is to call it: ' |
| 11756 | '"func(argument-list)".\n' |
| 11757 | '\n' |
| 11758 | 'There are really two flavors of function objects: built-in ' |
| 11759 | 'functions\n' |
| 11760 | 'and user-defined functions. Both support the same ' |
| 11761 | 'operation (to call\n' |
| 11762 | 'the function), but the implementation is different, hence ' |
| 11763 | 'the\n' |
| 11764 | 'different object types.\n' |
| 11765 | '\n' |
| 11766 | 'See Function definitions for more information.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 11767 | 'typesmapping': 'Mapping Types --- "dict"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 11768 | '************************\n' |
| 11769 | '\n' |
| 11770 | 'A *mapping* object maps *hashable* values to arbitrary ' |
| 11771 | 'objects.\n' |
| 11772 | 'Mappings are mutable objects. There is currently only one ' |
| 11773 | 'standard\n' |
| 11774 | 'mapping type, the *dictionary*. (For other containers see ' |
| 11775 | 'the built-\n' |
| 11776 | 'in "list", "set", and "tuple" classes, and the "collections" ' |
| 11777 | 'module.)\n' |
| 11778 | '\n' |
| 11779 | "A dictionary's keys are *almost* arbitrary values. Values " |
| 11780 | 'that are\n' |
| 11781 | 'not *hashable*, that is, values containing lists, ' |
| 11782 | 'dictionaries or\n' |
| 11783 | 'other mutable types (that are compared by value rather than ' |
| 11784 | 'by object\n' |
| 11785 | 'identity) may not be used as keys. Numeric types used for ' |
| 11786 | 'keys obey\n' |
| 11787 | 'the normal rules for numeric comparison: if two numbers ' |
| 11788 | 'compare equal\n' |
| 11789 | '(such as "1" and "1.0") then they can be used ' |
| 11790 | 'interchangeably to index\n' |
| 11791 | 'the same dictionary entry. (Note however, that since ' |
| 11792 | 'computers store\n' |
| 11793 | 'floating-point numbers as approximations it is usually ' |
| 11794 | 'unwise to use\n' |
| 11795 | 'them as dictionary keys.)\n' |
| 11796 | '\n' |
| 11797 | 'Dictionaries can be created by placing a comma-separated ' |
| 11798 | 'list of "key:\n' |
| 11799 | 'value" pairs within braces, for example: "{\'jack\': 4098, ' |
| 11800 | "'sjoerd':\n" |
| 11801 | '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the ' |
| 11802 | '"dict"\n' |
| 11803 | 'constructor.\n' |
| 11804 | '\n' |
| 11805 | 'class dict(**kwarg)\n' |
| 11806 | 'class dict(mapping, **kwarg)\n' |
| 11807 | 'class dict(iterable, **kwarg)\n' |
| 11808 | '\n' |
| 11809 | ' Return a new dictionary initialized from an optional ' |
| 11810 | 'positional\n' |
| 11811 | ' argument and a possibly empty set of keyword arguments.\n' |
| 11812 | '\n' |
| 11813 | ' If no positional argument is given, an empty dictionary ' |
| 11814 | 'is created.\n' |
| 11815 | ' If a positional argument is given and it is a mapping ' |
| 11816 | 'object, a\n' |
| 11817 | ' dictionary is created with the same key-value pairs as ' |
| 11818 | 'the mapping\n' |
| 11819 | ' object. Otherwise, the positional argument must be an ' |
| 11820 | '*iterable*\n' |
| 11821 | ' object. Each item in the iterable must itself be an ' |
| 11822 | 'iterable with\n' |
| 11823 | ' exactly two objects. The first object of each item ' |
| 11824 | 'becomes a key\n' |
| 11825 | ' in the new dictionary, and the second object the ' |
| 11826 | 'corresponding\n' |
| 11827 | ' value. If a key occurs more than once, the last value ' |
| 11828 | 'for that key\n' |
| 11829 | ' becomes the corresponding value in the new dictionary.\n' |
| 11830 | '\n' |
| 11831 | ' If keyword arguments are given, the keyword arguments and ' |
| 11832 | 'their\n' |
| 11833 | ' values are added to the dictionary created from the ' |
| 11834 | 'positional\n' |
| 11835 | ' argument. If a key being added is already present, the ' |
| 11836 | 'value from\n' |
| 11837 | ' the keyword argument replaces the value from the ' |
| 11838 | 'positional\n' |
| 11839 | ' argument.\n' |
| 11840 | '\n' |
| 11841 | ' To illustrate, the following examples all return a ' |
| 11842 | 'dictionary equal\n' |
| 11843 | ' to "{"one": 1, "two": 2, "three": 3}":\n' |
| 11844 | '\n' |
| 11845 | ' >>> a = dict(one=1, two=2, three=3)\n' |
| 11846 | " >>> b = {'one': 1, 'two': 2, 'three': 3}\n" |
| 11847 | " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n" |
| 11848 | " >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n" |
| 11849 | " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n" |
| 11850 | ' >>> a == b == c == d == e\n' |
| 11851 | ' True\n' |
| 11852 | '\n' |
| 11853 | ' Providing keyword arguments as in the first example only ' |
| 11854 | 'works for\n' |
| 11855 | ' keys that are valid Python identifiers. Otherwise, any ' |
| 11856 | 'valid keys\n' |
| 11857 | ' can be used.\n' |
| 11858 | '\n' |
| 11859 | ' These are the operations that dictionaries support (and ' |
| 11860 | 'therefore,\n' |
| 11861 | ' custom mapping types should support too):\n' |
| 11862 | '\n' |
| 11863 | ' len(d)\n' |
| 11864 | '\n' |
| 11865 | ' Return the number of items in the dictionary *d*.\n' |
| 11866 | '\n' |
| 11867 | ' d[key]\n' |
| 11868 | '\n' |
| 11869 | ' Return the item of *d* with key *key*. Raises a ' |
| 11870 | '"KeyError" if\n' |
| 11871 | ' *key* is not in the map.\n' |
| 11872 | '\n' |
| 11873 | ' If a subclass of dict defines a method "__missing__()" ' |
| 11874 | 'and *key*\n' |
| 11875 | ' is not present, the "d[key]" operation calls that ' |
| 11876 | 'method with\n' |
| 11877 | ' the key *key* as argument. The "d[key]" operation ' |
| 11878 | 'then returns\n' |
| 11879 | ' or raises whatever is returned or raised by the\n' |
| 11880 | ' "__missing__(key)" call. No other operations or ' |
| 11881 | 'methods invoke\n' |
| 11882 | ' "__missing__()". If "__missing__()" is not defined, ' |
| 11883 | '"KeyError"\n' |
| 11884 | ' is raised. "__missing__()" must be a method; it cannot ' |
| 11885 | 'be an\n' |
| 11886 | ' instance variable:\n' |
| 11887 | '\n' |
| 11888 | ' >>> class Counter(dict):\n' |
| 11889 | ' ... def __missing__(self, key):\n' |
| 11890 | ' ... return 0\n' |
| 11891 | ' >>> c = Counter()\n' |
| 11892 | " >>> c['red']\n" |
| 11893 | ' 0\n' |
| 11894 | " >>> c['red'] += 1\n" |
| 11895 | " >>> c['red']\n" |
| 11896 | ' 1\n' |
| 11897 | '\n' |
| 11898 | ' The example above shows part of the implementation of\n' |
| 11899 | ' "collections.Counter". A different "__missing__" ' |
| 11900 | 'method is used\n' |
| 11901 | ' by "collections.defaultdict".\n' |
| 11902 | '\n' |
| 11903 | ' d[key] = value\n' |
| 11904 | '\n' |
| 11905 | ' Set "d[key]" to *value*.\n' |
| 11906 | '\n' |
| 11907 | ' del d[key]\n' |
| 11908 | '\n' |
| 11909 | ' Remove "d[key]" from *d*. Raises a "KeyError" if ' |
| 11910 | '*key* is not\n' |
| 11911 | ' in the map.\n' |
| 11912 | '\n' |
| 11913 | ' key in d\n' |
| 11914 | '\n' |
| 11915 | ' Return "True" if *d* has a key *key*, else "False".\n' |
| 11916 | '\n' |
| 11917 | ' key not in d\n' |
| 11918 | '\n' |
| 11919 | ' Equivalent to "not key in d".\n' |
| 11920 | '\n' |
| 11921 | ' iter(d)\n' |
| 11922 | '\n' |
| 11923 | ' Return an iterator over the keys of the dictionary. ' |
| 11924 | 'This is a\n' |
| 11925 | ' shortcut for "iter(d.keys())".\n' |
| 11926 | '\n' |
| 11927 | ' clear()\n' |
| 11928 | '\n' |
| 11929 | ' Remove all items from the dictionary.\n' |
| 11930 | '\n' |
| 11931 | ' copy()\n' |
| 11932 | '\n' |
| 11933 | ' Return a shallow copy of the dictionary.\n' |
| 11934 | '\n' |
| 11935 | ' classmethod fromkeys(seq[, value])\n' |
| 11936 | '\n' |
| 11937 | ' Create a new dictionary with keys from *seq* and ' |
| 11938 | 'values set to\n' |
| 11939 | ' *value*.\n' |
| 11940 | '\n' |
| 11941 | ' "fromkeys()" is a class method that returns a new ' |
| 11942 | 'dictionary.\n' |
| 11943 | ' *value* defaults to "None".\n' |
| 11944 | '\n' |
| 11945 | ' get(key[, default])\n' |
| 11946 | '\n' |
| 11947 | ' Return the value for *key* if *key* is in the ' |
| 11948 | 'dictionary, else\n' |
| 11949 | ' *default*. If *default* is not given, it defaults to ' |
| 11950 | '"None", so\n' |
| 11951 | ' that this method never raises a "KeyError".\n' |
| 11952 | '\n' |
| 11953 | ' items()\n' |
| 11954 | '\n' |
| 11955 | ' Return a new view of the dictionary\'s items ("(key, ' |
| 11956 | 'value)"\n' |
| 11957 | ' pairs). See the documentation of view objects.\n' |
| 11958 | '\n' |
| 11959 | ' keys()\n' |
| 11960 | '\n' |
| 11961 | " Return a new view of the dictionary's keys. See the\n" |
| 11962 | ' documentation of view objects.\n' |
| 11963 | '\n' |
| 11964 | ' pop(key[, default])\n' |
| 11965 | '\n' |
| 11966 | ' If *key* is in the dictionary, remove it and return ' |
| 11967 | 'its value,\n' |
| 11968 | ' else return *default*. If *default* is not given and ' |
| 11969 | '*key* is\n' |
| 11970 | ' not in the dictionary, a "KeyError" is raised.\n' |
| 11971 | '\n' |
| 11972 | ' popitem()\n' |
| 11973 | '\n' |
| 11974 | ' Remove and return an arbitrary "(key, value)" pair ' |
| 11975 | 'from the\n' |
| 11976 | ' dictionary.\n' |
| 11977 | '\n' |
| 11978 | ' "popitem()" is useful to destructively iterate over a\n' |
| 11979 | ' dictionary, as often used in set algorithms. If the ' |
| 11980 | 'dictionary\n' |
| 11981 | ' is empty, calling "popitem()" raises a "KeyError".\n' |
| 11982 | '\n' |
| 11983 | ' setdefault(key[, default])\n' |
| 11984 | '\n' |
| 11985 | ' If *key* is in the dictionary, return its value. If ' |
| 11986 | 'not, insert\n' |
| 11987 | ' *key* with a value of *default* and return *default*. ' |
| 11988 | '*default*\n' |
| 11989 | ' defaults to "None".\n' |
| 11990 | '\n' |
| 11991 | ' update([other])\n' |
| 11992 | '\n' |
| 11993 | ' Update the dictionary with the key/value pairs from ' |
| 11994 | '*other*,\n' |
| 11995 | ' overwriting existing keys. Return "None".\n' |
| 11996 | '\n' |
| 11997 | ' "update()" accepts either another dictionary object or ' |
| 11998 | 'an\n' |
| 11999 | ' iterable of key/value pairs (as tuples or other ' |
| 12000 | 'iterables of\n' |
| 12001 | ' length two). If keyword arguments are specified, the ' |
| 12002 | 'dictionary\n' |
| 12003 | ' is then updated with those key/value pairs: ' |
| 12004 | '"d.update(red=1,\n' |
| 12005 | ' blue=2)".\n' |
| 12006 | '\n' |
| 12007 | ' values()\n' |
| 12008 | '\n' |
| 12009 | " Return a new view of the dictionary's values. See " |
| 12010 | 'the\n' |
| 12011 | ' documentation of view objects.\n' |
| 12012 | '\n' |
| 12013 | ' Dictionaries compare equal if and only if they have the ' |
| 12014 | 'same "(key,\n' |
| 12015 | ' value)" pairs. Order comparisons (\'<\', \'<=\', \'>=\', ' |
| 12016 | "'>') raise\n" |
| 12017 | ' "TypeError".\n' |
| 12018 | '\n' |
| 12019 | 'See also: "types.MappingProxyType" can be used to create a ' |
| 12020 | 'read-only\n' |
| 12021 | ' view of a "dict".\n' |
| 12022 | '\n' |
| 12023 | '\n' |
| 12024 | 'Dictionary view objects\n' |
| 12025 | '=======================\n' |
| 12026 | '\n' |
| 12027 | 'The objects returned by "dict.keys()", "dict.values()" and\n' |
| 12028 | '"dict.items()" are *view objects*. They provide a dynamic ' |
| 12029 | 'view on the\n' |
| 12030 | "dictionary's entries, which means that when the dictionary " |
| 12031 | 'changes,\n' |
| 12032 | 'the view reflects these changes.\n' |
| 12033 | '\n' |
| 12034 | 'Dictionary views can be iterated over to yield their ' |
| 12035 | 'respective data,\n' |
| 12036 | 'and support membership tests:\n' |
| 12037 | '\n' |
| 12038 | 'len(dictview)\n' |
| 12039 | '\n' |
| 12040 | ' Return the number of entries in the dictionary.\n' |
| 12041 | '\n' |
| 12042 | 'iter(dictview)\n' |
| 12043 | '\n' |
| 12044 | ' Return an iterator over the keys, values or items ' |
| 12045 | '(represented as\n' |
| 12046 | ' tuples of "(key, value)") in the dictionary.\n' |
| 12047 | '\n' |
| 12048 | ' Keys and values are iterated over in an arbitrary order ' |
| 12049 | 'which is\n' |
| 12050 | ' non-random, varies across Python implementations, and ' |
| 12051 | 'depends on\n' |
| 12052 | " the dictionary's history of insertions and deletions. If " |
| 12053 | 'keys,\n' |
| 12054 | ' values and items views are iterated over with no ' |
| 12055 | 'intervening\n' |
| 12056 | ' modifications to the dictionary, the order of items will ' |
| 12057 | 'directly\n' |
| 12058 | ' correspond. This allows the creation of "(value, key)" ' |
| 12059 | 'pairs using\n' |
| 12060 | ' "zip()": "pairs = zip(d.values(), d.keys())". Another ' |
| 12061 | 'way to\n' |
| 12062 | ' create the same list is "pairs = [(v, k) for (k, v) in ' |
| 12063 | 'd.items()]".\n' |
| 12064 | '\n' |
| 12065 | ' Iterating views while adding or deleting entries in the ' |
| 12066 | 'dictionary\n' |
| 12067 | ' may raise a "RuntimeError" or fail to iterate over all ' |
| 12068 | 'entries.\n' |
| 12069 | '\n' |
| 12070 | 'x in dictview\n' |
| 12071 | '\n' |
| 12072 | ' Return "True" if *x* is in the underlying dictionary\'s ' |
| 12073 | 'keys, values\n' |
| 12074 | ' or items (in the latter case, *x* should be a "(key, ' |
| 12075 | 'value)"\n' |
| 12076 | ' tuple).\n' |
| 12077 | '\n' |
| 12078 | 'Keys views are set-like since their entries are unique and ' |
| 12079 | 'hashable.\n' |
| 12080 | 'If all values are hashable, so that "(key, value)" pairs are ' |
| 12081 | 'unique\n' |
| 12082 | 'and hashable, then the items view is also set-like. (Values ' |
| 12083 | 'views are\n' |
| 12084 | 'not treated as set-like since the entries are generally not ' |
| 12085 | 'unique.)\n' |
| 12086 | 'For set-like views, all of the operations defined for the ' |
| 12087 | 'abstract\n' |
| 12088 | 'base class "collections.abc.Set" are available (for example, ' |
| 12089 | '"==",\n' |
| 12090 | '"<", or "^").\n' |
| 12091 | '\n' |
| 12092 | 'An example of dictionary view usage:\n' |
| 12093 | '\n' |
| 12094 | " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, " |
| 12095 | "'spam': 500}\n" |
| 12096 | ' >>> keys = dishes.keys()\n' |
| 12097 | ' >>> values = dishes.values()\n' |
| 12098 | '\n' |
| 12099 | ' >>> # iteration\n' |
| 12100 | ' >>> n = 0\n' |
| 12101 | ' >>> for val in values:\n' |
| 12102 | ' ... n += val\n' |
| 12103 | ' >>> print(n)\n' |
| 12104 | ' 504\n' |
| 12105 | '\n' |
| 12106 | ' >>> # keys and values are iterated over in the same ' |
| 12107 | 'order\n' |
| 12108 | ' >>> list(keys)\n' |
| 12109 | " ['eggs', 'bacon', 'sausage', 'spam']\n" |
| 12110 | ' >>> list(values)\n' |
| 12111 | ' [2, 1, 1, 500]\n' |
| 12112 | '\n' |
| 12113 | ' >>> # view objects are dynamic and reflect dict changes\n' |
| 12114 | " >>> del dishes['eggs']\n" |
| 12115 | " >>> del dishes['sausage']\n" |
| 12116 | ' >>> list(keys)\n' |
| 12117 | " ['spam', 'bacon']\n" |
| 12118 | '\n' |
| 12119 | ' >>> # set operations\n' |
| 12120 | " >>> keys & {'eggs', 'bacon', 'salad'}\n" |
| 12121 | " {'bacon'}\n" |
| 12122 | " >>> keys ^ {'sausage', 'juice'}\n" |
| 12123 | " {'juice', 'sausage', 'bacon', 'spam'}\n", |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12124 | 'typesmethods': 'Methods\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12125 | '*******\n' |
| 12126 | '\n' |
| 12127 | 'Methods are functions that are called using the attribute ' |
| 12128 | 'notation.\n' |
| 12129 | 'There are two flavors: built-in methods (such as "append()" ' |
| 12130 | 'on lists)\n' |
| 12131 | 'and class instance methods. Built-in methods are described ' |
| 12132 | 'with the\n' |
| 12133 | 'types that support them.\n' |
| 12134 | '\n' |
| 12135 | 'If you access a method (a function defined in a class ' |
| 12136 | 'namespace)\n' |
| 12137 | 'through an instance, you get a special object: a *bound ' |
| 12138 | 'method* (also\n' |
| 12139 | 'called *instance method*) object. When called, it will add ' |
| 12140 | 'the "self"\n' |
| 12141 | 'argument to the argument list. Bound methods have two ' |
| 12142 | 'special read-\n' |
| 12143 | 'only attributes: "m.__self__" is the object on which the ' |
| 12144 | 'method\n' |
| 12145 | 'operates, and "m.__func__" is the function implementing the ' |
| 12146 | 'method.\n' |
| 12147 | 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely ' |
| 12148 | 'equivalent to\n' |
| 12149 | 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n' |
| 12150 | '\n' |
| 12151 | 'Like function objects, bound method objects support getting ' |
| 12152 | 'arbitrary\n' |
| 12153 | 'attributes. However, since method attributes are actually ' |
| 12154 | 'stored on\n' |
| 12155 | 'the underlying function object ("meth.__func__"), setting ' |
| 12156 | 'method\n' |
| 12157 | 'attributes on bound methods is disallowed. Attempting to ' |
| 12158 | 'set an\n' |
| 12159 | 'attribute on a method results in an "AttributeError" being ' |
| 12160 | 'raised. In\n' |
| 12161 | 'order to set a method attribute, you need to explicitly set ' |
| 12162 | 'it on the\n' |
| 12163 | 'underlying function object:\n' |
| 12164 | '\n' |
| 12165 | ' >>> class C:\n' |
| 12166 | ' ... def method(self):\n' |
| 12167 | ' ... pass\n' |
| 12168 | ' ...\n' |
| 12169 | ' >>> c = C()\n' |
| 12170 | " >>> c.method.whoami = 'my name is method' # can't set on " |
| 12171 | 'the method\n' |
| 12172 | ' Traceback (most recent call last):\n' |
| 12173 | ' File "<stdin>", line 1, in <module>\n' |
| 12174 | " AttributeError: 'method' object has no attribute " |
| 12175 | "'whoami'\n" |
| 12176 | " >>> c.method.__func__.whoami = 'my name is method'\n" |
| 12177 | ' >>> c.method.whoami\n' |
| 12178 | " 'my name is method'\n" |
| 12179 | '\n' |
| 12180 | 'See The standard type hierarchy for more information.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12181 | 'typesmodules': 'Modules\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12182 | '*******\n' |
| 12183 | '\n' |
| 12184 | 'The only special operation on a module is attribute access: ' |
| 12185 | '"m.name",\n' |
| 12186 | 'where *m* is a module and *name* accesses a name defined in ' |
| 12187 | "*m*'s\n" |
| 12188 | 'symbol table. Module attributes can be assigned to. (Note ' |
| 12189 | 'that the\n' |
| 12190 | '"import" statement is not, strictly speaking, an operation ' |
| 12191 | 'on a module\n' |
| 12192 | 'object; "import foo" does not require a module object named ' |
| 12193 | '*foo* to\n' |
| 12194 | 'exist, rather it requires an (external) *definition* for a ' |
| 12195 | 'module\n' |
| 12196 | 'named *foo* somewhere.)\n' |
| 12197 | '\n' |
| 12198 | 'A special attribute of every module is "__dict__". This is ' |
| 12199 | 'the\n' |
| 12200 | "dictionary containing the module's symbol table. Modifying " |
| 12201 | 'this\n' |
| 12202 | "dictionary will actually change the module's symbol table, " |
| 12203 | 'but direct\n' |
| 12204 | 'assignment to the "__dict__" attribute is not possible (you ' |
| 12205 | 'can write\n' |
| 12206 | '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but ' |
| 12207 | "you can't\n" |
| 12208 | 'write "m.__dict__ = {}"). Modifying "__dict__" directly is ' |
| 12209 | 'not\n' |
| 12210 | 'recommended.\n' |
| 12211 | '\n' |
| 12212 | 'Modules built into the interpreter are written like this: ' |
| 12213 | '"<module\n' |
| 12214 | '\'sys\' (built-in)>". If loaded from a file, they are ' |
| 12215 | 'written as\n' |
| 12216 | '"<module \'os\' from ' |
| 12217 | '\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12218 | 'typesseq': 'Sequence Types --- "list", "tuple", "range"\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12219 | '*******************************************\n' |
| 12220 | '\n' |
| 12221 | 'There are three basic sequence types: lists, tuples, and range\n' |
| 12222 | 'objects. Additional sequence types tailored for processing of ' |
| 12223 | 'binary\n' |
| 12224 | 'data and text strings are described in dedicated sections.\n' |
| 12225 | '\n' |
| 12226 | '\n' |
| 12227 | 'Common Sequence Operations\n' |
| 12228 | '==========================\n' |
| 12229 | '\n' |
| 12230 | 'The operations in the following table are supported by most ' |
| 12231 | 'sequence\n' |
| 12232 | 'types, both mutable and immutable. The ' |
| 12233 | '"collections.abc.Sequence" ABC\n' |
| 12234 | 'is provided to make it easier to correctly implement these ' |
| 12235 | 'operations\n' |
| 12236 | 'on custom sequence types.\n' |
| 12237 | '\n' |
| 12238 | 'This table lists the sequence operations sorted in ascending ' |
| 12239 | 'priority.\n' |
| 12240 | 'In the table, *s* and *t* are sequences of the same type, *n*, ' |
| 12241 | '*i*,\n' |
| 12242 | '*j* and *k* are integers and *x* is an arbitrary object that ' |
| 12243 | 'meets any\n' |
| 12244 | 'type and value restrictions imposed by *s*.\n' |
| 12245 | '\n' |
| 12246 | 'The "in" and "not in" operations have the same priorities as ' |
| 12247 | 'the\n' |
| 12248 | 'comparison operations. The "+" (concatenation) and "*" ' |
| 12249 | '(repetition)\n' |
| 12250 | 'operations have the same priority as the corresponding numeric\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12251 | 'operations. [3]\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12252 | '\n' |
| 12253 | '+----------------------------+----------------------------------+------------+\n' |
| 12254 | '| Operation | Result ' |
| 12255 | '| Notes |\n' |
| 12256 | '+============================+==================================+============+\n' |
| 12257 | '| "x in s" | "True" if an item of *s* is ' |
| 12258 | '| (1) |\n' |
| 12259 | '| | equal to *x*, else "False" ' |
| 12260 | '| |\n' |
| 12261 | '+----------------------------+----------------------------------+------------+\n' |
| 12262 | '| "x not in s" | "False" if an item of *s* is ' |
| 12263 | '| (1) |\n' |
| 12264 | '| | equal to *x*, else "True" ' |
| 12265 | '| |\n' |
| 12266 | '+----------------------------+----------------------------------+------------+\n' |
| 12267 | '| "s + t" | the concatenation of *s* and *t* ' |
| 12268 | '| (6)(7) |\n' |
| 12269 | '+----------------------------+----------------------------------+------------+\n' |
| 12270 | '| "s * n" or "n * s" | equivalent to adding *s* to ' |
| 12271 | '| (2)(7) |\n' |
| 12272 | '| | itself *n* times ' |
| 12273 | '| |\n' |
| 12274 | '+----------------------------+----------------------------------+------------+\n' |
| 12275 | '| "s[i]" | *i*th item of *s*, origin 0 ' |
| 12276 | '| (3) |\n' |
| 12277 | '+----------------------------+----------------------------------+------------+\n' |
| 12278 | '| "s[i:j]" | slice of *s* from *i* to *j* ' |
| 12279 | '| (3)(4) |\n' |
| 12280 | '+----------------------------+----------------------------------+------------+\n' |
| 12281 | '| "s[i:j:k]" | slice of *s* from *i* to *j* ' |
| 12282 | '| (3)(5) |\n' |
| 12283 | '| | with step *k* ' |
| 12284 | '| |\n' |
| 12285 | '+----------------------------+----------------------------------+------------+\n' |
| 12286 | '| "len(s)" | length of *s* ' |
| 12287 | '| |\n' |
| 12288 | '+----------------------------+----------------------------------+------------+\n' |
| 12289 | '| "min(s)" | smallest item of *s* ' |
| 12290 | '| |\n' |
| 12291 | '+----------------------------+----------------------------------+------------+\n' |
| 12292 | '| "max(s)" | largest item of *s* ' |
| 12293 | '| |\n' |
| 12294 | '+----------------------------+----------------------------------+------------+\n' |
| 12295 | '| "s.index(x[, i[, j]])" | index of the first occurrence of ' |
| 12296 | '| (8) |\n' |
| 12297 | '| | *x* in *s* (at or after index ' |
| 12298 | '| |\n' |
| 12299 | '| | *i* and before index *j*) ' |
| 12300 | '| |\n' |
| 12301 | '+----------------------------+----------------------------------+------------+\n' |
| 12302 | '| "s.count(x)" | total number of occurrences of ' |
| 12303 | '| |\n' |
| 12304 | '| | *x* in *s* ' |
| 12305 | '| |\n' |
| 12306 | '+----------------------------+----------------------------------+------------+\n' |
| 12307 | '\n' |
| 12308 | 'Sequences of the same type also support comparisons. In ' |
| 12309 | 'particular,\n' |
| 12310 | 'tuples and lists are compared lexicographically by comparing\n' |
| 12311 | 'corresponding elements. This means that to compare equal, every\n' |
| 12312 | 'element must compare equal and the two sequences must be of the ' |
| 12313 | 'same\n' |
| 12314 | 'type and have the same length. (For full details see ' |
| 12315 | 'Comparisons in\n' |
| 12316 | 'the language reference.)\n' |
| 12317 | '\n' |
| 12318 | 'Notes:\n' |
| 12319 | '\n' |
| 12320 | '1. While the "in" and "not in" operations are used only for ' |
| 12321 | 'simple\n' |
| 12322 | ' containment testing in the general case, some specialised ' |
| 12323 | 'sequences\n' |
| 12324 | ' (such as "str", "bytes" and "bytearray") also use them for\n' |
| 12325 | ' subsequence testing:\n' |
| 12326 | '\n' |
| 12327 | ' >>> "gg" in "eggs"\n' |
| 12328 | ' True\n' |
| 12329 | '\n' |
| 12330 | '2. Values of *n* less than "0" are treated as "0" (which yields ' |
| 12331 | 'an\n' |
| 12332 | ' empty sequence of the same type as *s*). Note that items in ' |
| 12333 | 'the\n' |
| 12334 | ' sequence *s* are not copied; they are referenced multiple ' |
| 12335 | 'times.\n' |
| 12336 | ' This often haunts new Python programmers; consider:\n' |
| 12337 | '\n' |
| 12338 | ' >>> lists = [[]] * 3\n' |
| 12339 | ' >>> lists\n' |
| 12340 | ' [[], [], []]\n' |
| 12341 | ' >>> lists[0].append(3)\n' |
| 12342 | ' >>> lists\n' |
| 12343 | ' [[3], [3], [3]]\n' |
| 12344 | '\n' |
| 12345 | ' What has happened is that "[[]]" is a one-element list ' |
| 12346 | 'containing\n' |
| 12347 | ' an empty list, so all three elements of "[[]] * 3" are ' |
| 12348 | 'references\n' |
| 12349 | ' to this single empty list. Modifying any of the elements of\n' |
| 12350 | ' "lists" modifies this single list. You can create a list of\n' |
| 12351 | ' different lists this way:\n' |
| 12352 | '\n' |
| 12353 | ' >>> lists = [[] for i in range(3)]\n' |
| 12354 | ' >>> lists[0].append(3)\n' |
| 12355 | ' >>> lists[1].append(5)\n' |
| 12356 | ' >>> lists[2].append(7)\n' |
| 12357 | ' >>> lists\n' |
| 12358 | ' [[3], [5], [7]]\n' |
| 12359 | '\n' |
| 12360 | ' Further explanation is available in the FAQ entry How do I ' |
| 12361 | 'create a\n' |
| 12362 | ' multidimensional list?.\n' |
| 12363 | '\n' |
| 12364 | '3. If *i* or *j* is negative, the index is relative to the end ' |
| 12365 | 'of\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12366 | ' sequence *s*: "len(s) + i" or "len(s) + j" is substituted. ' |
| 12367 | 'But\n' |
| 12368 | ' note that "-0" is still "0".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12369 | '\n' |
| 12370 | '4. The slice of *s* from *i* to *j* is defined as the sequence ' |
| 12371 | 'of\n' |
| 12372 | ' items with index *k* such that "i <= k < j". If *i* or *j* ' |
| 12373 | 'is\n' |
| 12374 | ' greater than "len(s)", use "len(s)". If *i* is omitted or ' |
| 12375 | '"None",\n' |
| 12376 | ' use "0". If *j* is omitted or "None", use "len(s)". If *i* ' |
| 12377 | 'is\n' |
| 12378 | ' greater than or equal to *j*, the slice is empty.\n' |
| 12379 | '\n' |
| 12380 | '5. The slice of *s* from *i* to *j* with step *k* is defined as ' |
| 12381 | 'the\n' |
| 12382 | ' sequence of items with index "x = i + n*k" such that "0 <= n ' |
| 12383 | '<\n' |
| 12384 | ' (j-i)/k". In other words, the indices are "i", "i+k", ' |
| 12385 | '"i+2*k",\n' |
| 12386 | ' "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] | 12387 | ' including *j*). When *k* is positive, *i* and *j* are ' |
| 12388 | 'reduced to\n' |
| 12389 | ' "len(s)" if they are greater. When *k* is negative, *i* and ' |
| 12390 | '*j* are\n' |
| 12391 | ' reduced to "len(s) - 1" if they are greater. If *i* or *j* ' |
| 12392 | 'are\n' |
| 12393 | ' omitted or "None", they become "end" values (which end ' |
| 12394 | 'depends on\n' |
| 12395 | ' the sign of *k*). Note, *k* cannot be zero. If *k* is ' |
| 12396 | '"None", it\n' |
| 12397 | ' is treated like "1".\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12398 | '\n' |
| 12399 | '6. Concatenating immutable sequences always results in a new\n' |
| 12400 | ' object. This means that building up a sequence by repeated\n' |
| 12401 | ' concatenation will have a quadratic runtime cost in the ' |
| 12402 | 'total\n' |
| 12403 | ' sequence length. To get a linear runtime cost, you must ' |
| 12404 | 'switch to\n' |
| 12405 | ' one of the alternatives below:\n' |
| 12406 | '\n' |
| 12407 | ' * if concatenating "str" objects, you can build a list and ' |
| 12408 | 'use\n' |
| 12409 | ' "str.join()" at the end or else write to an "io.StringIO"\n' |
| 12410 | ' instance and retrieve its value when complete\n' |
| 12411 | '\n' |
| 12412 | ' * if concatenating "bytes" objects, you can similarly use\n' |
| 12413 | ' "bytes.join()" or "io.BytesIO", or you can do in-place\n' |
| 12414 | ' concatenation with a "bytearray" object. "bytearray" ' |
| 12415 | 'objects are\n' |
| 12416 | ' mutable and have an efficient overallocation mechanism\n' |
| 12417 | '\n' |
| 12418 | ' * if concatenating "tuple" objects, extend a "list" instead\n' |
| 12419 | '\n' |
| 12420 | ' * for other types, investigate the relevant class ' |
| 12421 | 'documentation\n' |
| 12422 | '\n' |
| 12423 | '7. Some sequence types (such as "range") only support item\n' |
| 12424 | " sequences that follow specific patterns, and hence don't " |
| 12425 | 'support\n' |
| 12426 | ' sequence concatenation or repetition.\n' |
| 12427 | '\n' |
| 12428 | '8. "index" raises "ValueError" when *x* is not found in *s*. ' |
Ned Deily | 3b43bfa | 2018-01-08 21:57:13 -0500 | [diff] [blame] | 12429 | 'Not\n' |
| 12430 | ' all implementations support passing the additional arguments ' |
| 12431 | '*i*\n' |
| 12432 | ' and *j*. These arguments allow efficient searching of ' |
| 12433 | 'subsections\n' |
| 12434 | ' of the sequence. Passing the extra arguments is roughly ' |
| 12435 | 'equivalent\n' |
| 12436 | ' to using "s[i:j].index(x)", only without copying any data and ' |
| 12437 | 'with\n' |
| 12438 | ' the returned index being relative to the start of the ' |
| 12439 | 'sequence\n' |
| 12440 | ' rather than the start of the slice.\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12441 | '\n' |
| 12442 | '\n' |
| 12443 | 'Immutable Sequence Types\n' |
| 12444 | '========================\n' |
| 12445 | '\n' |
| 12446 | 'The only operation that immutable sequence types generally ' |
| 12447 | 'implement\n' |
| 12448 | 'that is not also implemented by mutable sequence types is ' |
| 12449 | 'support for\n' |
| 12450 | 'the "hash()" built-in.\n' |
| 12451 | '\n' |
| 12452 | 'This support allows immutable sequences, such as "tuple" ' |
| 12453 | 'instances, to\n' |
| 12454 | 'be used as "dict" keys and stored in "set" and "frozenset" ' |
| 12455 | 'instances.\n' |
| 12456 | '\n' |
| 12457 | 'Attempting to hash an immutable sequence that contains ' |
| 12458 | 'unhashable\n' |
| 12459 | 'values will result in "TypeError".\n' |
| 12460 | '\n' |
| 12461 | '\n' |
| 12462 | 'Mutable Sequence Types\n' |
| 12463 | '======================\n' |
| 12464 | '\n' |
| 12465 | 'The operations in the following table are defined on mutable ' |
| 12466 | 'sequence\n' |
| 12467 | 'types. The "collections.abc.MutableSequence" ABC is provided to ' |
| 12468 | 'make\n' |
| 12469 | 'it easier to correctly implement these operations on custom ' |
| 12470 | 'sequence\n' |
| 12471 | 'types.\n' |
| 12472 | '\n' |
| 12473 | 'In the table *s* is an instance of a mutable sequence type, *t* ' |
| 12474 | 'is any\n' |
| 12475 | 'iterable object and *x* is an arbitrary object that meets any ' |
| 12476 | 'type and\n' |
| 12477 | 'value restrictions imposed by *s* (for example, "bytearray" ' |
| 12478 | 'only\n' |
| 12479 | 'accepts integers that meet the value restriction "0 <= x <= ' |
| 12480 | '255").\n' |
| 12481 | '\n' |
| 12482 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12483 | '| Operation | ' |
| 12484 | 'Result | Notes |\n' |
| 12485 | '+================================+==================================+=======================+\n' |
| 12486 | '| "s[i] = x" | item *i* of *s* is replaced ' |
| 12487 | 'by | |\n' |
| 12488 | '| | ' |
| 12489 | '*x* | |\n' |
| 12490 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12491 | '| "s[i:j] = t" | slice of *s* from *i* to *j* ' |
| 12492 | 'is | |\n' |
| 12493 | '| | replaced by the contents of ' |
| 12494 | 'the | |\n' |
| 12495 | '| | iterable ' |
| 12496 | '*t* | |\n' |
| 12497 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12498 | '| "del s[i:j]" | same as "s[i:j] = ' |
| 12499 | '[]" | |\n' |
| 12500 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12501 | '| "s[i:j:k] = t" | the elements of "s[i:j:k]" ' |
| 12502 | 'are | (1) |\n' |
| 12503 | '| | replaced by those of ' |
| 12504 | '*t* | |\n' |
| 12505 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12506 | '| "del s[i:j:k]" | removes the elements ' |
| 12507 | 'of | |\n' |
| 12508 | '| | "s[i:j:k]" from the ' |
| 12509 | 'list | |\n' |
| 12510 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12511 | '| "s.append(x)" | appends *x* to the end of ' |
| 12512 | 'the | |\n' |
| 12513 | '| | sequence (same ' |
| 12514 | 'as | |\n' |
| 12515 | '| | "s[len(s):len(s)] = ' |
| 12516 | '[x]") | |\n' |
| 12517 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12518 | '| "s.clear()" | removes all items from "s" ' |
| 12519 | '(same | (5) |\n' |
| 12520 | '| | as "del ' |
| 12521 | 's[:]") | |\n' |
| 12522 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12523 | '| "s.copy()" | creates a shallow copy of ' |
| 12524 | '"s" | (5) |\n' |
| 12525 | '| | (same as ' |
| 12526 | '"s[:]") | |\n' |
| 12527 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12528 | '| "s.extend(t)" or "s += t" | extends *s* with the contents ' |
| 12529 | 'of | |\n' |
| 12530 | '| | *t* (for the most part the ' |
| 12531 | 'same | |\n' |
| 12532 | '| | as "s[len(s):len(s)] = ' |
| 12533 | 't") | |\n' |
| 12534 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12535 | '| "s *= n" | updates *s* with its ' |
| 12536 | 'contents | (6) |\n' |
| 12537 | '| | repeated *n* ' |
| 12538 | 'times | |\n' |
| 12539 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12540 | '| "s.insert(i, x)" | inserts *x* into *s* at ' |
| 12541 | 'the | |\n' |
| 12542 | '| | index given by *i* (same ' |
| 12543 | 'as | |\n' |
| 12544 | '| | "s[i:i] = ' |
| 12545 | '[x]") | |\n' |
| 12546 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12547 | '| "s.pop([i])" | retrieves the item at *i* ' |
| 12548 | 'and | (2) |\n' |
| 12549 | '| | also removes it from ' |
| 12550 | '*s* | |\n' |
| 12551 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12552 | '| "s.remove(x)" | remove the first item from ' |
| 12553 | '*s* | (3) |\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12554 | '| | where "s[i]" is equal to ' |
| 12555 | '*x* | |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12556 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12557 | '| "s.reverse()" | reverses the items of *s* ' |
| 12558 | 'in | (4) |\n' |
| 12559 | '| | ' |
| 12560 | 'place | |\n' |
| 12561 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12562 | '\n' |
| 12563 | 'Notes:\n' |
| 12564 | '\n' |
| 12565 | '1. *t* must have the same length as the slice it is replacing.\n' |
| 12566 | '\n' |
| 12567 | '2. The optional argument *i* defaults to "-1", so that by ' |
| 12568 | 'default\n' |
| 12569 | ' the last item is removed and returned.\n' |
| 12570 | '\n' |
| 12571 | '3. "remove" raises "ValueError" when *x* is not found in *s*.\n' |
| 12572 | '\n' |
| 12573 | '4. The "reverse()" method modifies the sequence in place for\n' |
| 12574 | ' economy of space when reversing a large sequence. To remind ' |
| 12575 | 'users\n' |
| 12576 | ' that it operates by side effect, it does not return the ' |
| 12577 | 'reversed\n' |
| 12578 | ' sequence.\n' |
| 12579 | '\n' |
| 12580 | '5. "clear()" and "copy()" are included for consistency with the\n' |
| 12581 | " interfaces of mutable containers that don't support slicing\n" |
| 12582 | ' operations (such as "dict" and "set")\n' |
| 12583 | '\n' |
| 12584 | ' New in version 3.3: "clear()" and "copy()" methods.\n' |
| 12585 | '\n' |
| 12586 | '6. The value *n* is an integer, or an object implementing\n' |
| 12587 | ' "__index__()". Zero and negative values of *n* clear the ' |
| 12588 | 'sequence.\n' |
| 12589 | ' Items in the sequence are not copied; they are referenced ' |
| 12590 | 'multiple\n' |
| 12591 | ' times, as explained for "s * n" under Common Sequence ' |
| 12592 | 'Operations.\n' |
| 12593 | '\n' |
| 12594 | '\n' |
| 12595 | 'Lists\n' |
| 12596 | '=====\n' |
| 12597 | '\n' |
| 12598 | 'Lists are mutable sequences, typically used to store collections ' |
| 12599 | 'of\n' |
| 12600 | 'homogeneous items (where the precise degree of similarity will ' |
| 12601 | 'vary by\n' |
| 12602 | 'application).\n' |
| 12603 | '\n' |
| 12604 | 'class list([iterable])\n' |
| 12605 | '\n' |
| 12606 | ' Lists may be constructed in several ways:\n' |
| 12607 | '\n' |
| 12608 | ' * Using a pair of square brackets to denote the empty list: ' |
| 12609 | '"[]"\n' |
| 12610 | '\n' |
| 12611 | ' * Using square brackets, separating items with commas: ' |
| 12612 | '"[a]",\n' |
| 12613 | ' "[a, b, c]"\n' |
| 12614 | '\n' |
| 12615 | ' * Using a list comprehension: "[x for x in iterable]"\n' |
| 12616 | '\n' |
| 12617 | ' * Using the type constructor: "list()" or "list(iterable)"\n' |
| 12618 | '\n' |
| 12619 | ' The constructor builds a list whose items are the same and in ' |
| 12620 | 'the\n' |
| 12621 | " same order as *iterable*'s items. *iterable* may be either " |
| 12622 | 'a\n' |
| 12623 | ' sequence, a container that supports iteration, or an ' |
| 12624 | 'iterator\n' |
| 12625 | ' object. If *iterable* is already a list, a copy is made and\n' |
| 12626 | ' returned, similar to "iterable[:]". For example, ' |
| 12627 | '"list(\'abc\')"\n' |
| 12628 | ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" ' |
| 12629 | 'returns "[1, 2,\n' |
| 12630 | ' 3]". If no argument is given, the constructor creates a new ' |
| 12631 | 'empty\n' |
| 12632 | ' list, "[]".\n' |
| 12633 | '\n' |
| 12634 | ' Many other operations also produce lists, including the ' |
| 12635 | '"sorted()"\n' |
| 12636 | ' built-in.\n' |
| 12637 | '\n' |
| 12638 | ' Lists implement all of the common and mutable sequence ' |
| 12639 | 'operations.\n' |
| 12640 | ' Lists also provide the following additional method:\n' |
| 12641 | '\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12642 | ' sort(*, key=None, reverse=False)\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12643 | '\n' |
| 12644 | ' This method sorts the list in place, using only "<" ' |
| 12645 | 'comparisons\n' |
| 12646 | ' between items. Exceptions are not suppressed - if any ' |
| 12647 | 'comparison\n' |
| 12648 | ' operations fail, the entire sort operation will fail (and ' |
| 12649 | 'the\n' |
| 12650 | ' list will likely be left in a partially modified state).\n' |
| 12651 | '\n' |
| 12652 | ' "sort()" accepts two arguments that can only be passed by\n' |
| 12653 | ' keyword (keyword-only arguments):\n' |
| 12654 | '\n' |
| 12655 | ' *key* specifies a function of one argument that is used ' |
| 12656 | 'to\n' |
| 12657 | ' extract a comparison key from each list element (for ' |
| 12658 | 'example,\n' |
| 12659 | ' "key=str.lower"). The key corresponding to each item in ' |
| 12660 | 'the list\n' |
| 12661 | ' is calculated once and then used for the entire sorting ' |
| 12662 | 'process.\n' |
| 12663 | ' The default value of "None" means that list items are ' |
| 12664 | 'sorted\n' |
| 12665 | ' directly without calculating a separate key value.\n' |
| 12666 | '\n' |
| 12667 | ' The "functools.cmp_to_key()" utility is available to ' |
| 12668 | 'convert a\n' |
| 12669 | ' 2.x style *cmp* function to a *key* function.\n' |
| 12670 | '\n' |
| 12671 | ' *reverse* is a boolean value. If set to "True", then the ' |
| 12672 | 'list\n' |
| 12673 | ' elements are sorted as if each comparison were reversed.\n' |
| 12674 | '\n' |
| 12675 | ' This method modifies the sequence in place for economy of ' |
| 12676 | 'space\n' |
| 12677 | ' when sorting a large sequence. To remind users that it ' |
| 12678 | 'operates\n' |
| 12679 | ' by side effect, it does not return the sorted sequence ' |
| 12680 | '(use\n' |
| 12681 | ' "sorted()" to explicitly request a new sorted list ' |
| 12682 | 'instance).\n' |
| 12683 | '\n' |
| 12684 | ' The "sort()" method is guaranteed to be stable. A sort ' |
| 12685 | 'is\n' |
| 12686 | ' stable if it guarantees not to change the relative order ' |
| 12687 | 'of\n' |
| 12688 | ' elements that compare equal --- this is helpful for ' |
| 12689 | 'sorting in\n' |
| 12690 | ' multiple passes (for example, sort by department, then by ' |
| 12691 | 'salary\n' |
| 12692 | ' grade).\n' |
| 12693 | '\n' |
| 12694 | ' **CPython implementation detail:** While a list is being ' |
| 12695 | 'sorted,\n' |
| 12696 | ' the effect of attempting to mutate, or even inspect, the ' |
| 12697 | 'list is\n' |
| 12698 | ' undefined. The C implementation of Python makes the list ' |
| 12699 | 'appear\n' |
| 12700 | ' empty for the duration, and raises "ValueError" if it can ' |
| 12701 | 'detect\n' |
| 12702 | ' that the list has been mutated during a sort.\n' |
| 12703 | '\n' |
| 12704 | '\n' |
| 12705 | 'Tuples\n' |
| 12706 | '======\n' |
| 12707 | '\n' |
| 12708 | 'Tuples are immutable sequences, typically used to store ' |
| 12709 | 'collections of\n' |
| 12710 | 'heterogeneous data (such as the 2-tuples produced by the ' |
| 12711 | '"enumerate()"\n' |
| 12712 | 'built-in). Tuples are also used for cases where an immutable ' |
| 12713 | 'sequence\n' |
| 12714 | 'of homogeneous data is needed (such as allowing storage in a ' |
| 12715 | '"set" or\n' |
| 12716 | '"dict" instance).\n' |
| 12717 | '\n' |
| 12718 | 'class tuple([iterable])\n' |
| 12719 | '\n' |
| 12720 | ' Tuples may be constructed in a number of ways:\n' |
| 12721 | '\n' |
| 12722 | ' * Using a pair of parentheses to denote the empty tuple: ' |
| 12723 | '"()"\n' |
| 12724 | '\n' |
| 12725 | ' * Using a trailing comma for a singleton tuple: "a," or ' |
| 12726 | '"(a,)"\n' |
| 12727 | '\n' |
| 12728 | ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n' |
| 12729 | '\n' |
| 12730 | ' * Using the "tuple()" built-in: "tuple()" or ' |
| 12731 | '"tuple(iterable)"\n' |
| 12732 | '\n' |
| 12733 | ' The constructor builds a tuple whose items are the same and ' |
| 12734 | 'in the\n' |
| 12735 | " same order as *iterable*'s items. *iterable* may be either " |
| 12736 | 'a\n' |
| 12737 | ' sequence, a container that supports iteration, or an ' |
| 12738 | 'iterator\n' |
| 12739 | ' object. If *iterable* is already a tuple, it is returned\n' |
| 12740 | ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', ' |
| 12741 | '\'b\', \'c\')"\n' |
| 12742 | ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument ' |
| 12743 | 'is\n' |
| 12744 | ' given, the constructor creates a new empty tuple, "()".\n' |
| 12745 | '\n' |
| 12746 | ' Note that it is actually the comma which makes a tuple, not ' |
| 12747 | 'the\n' |
| 12748 | ' parentheses. The parentheses are optional, except in the ' |
| 12749 | 'empty\n' |
| 12750 | ' tuple case, or when they are needed to avoid syntactic ' |
| 12751 | 'ambiguity.\n' |
| 12752 | ' For example, "f(a, b, c)" is a function call with three ' |
| 12753 | 'arguments,\n' |
| 12754 | ' while "f((a, b, c))" is a function call with a 3-tuple as the ' |
| 12755 | 'sole\n' |
| 12756 | ' argument.\n' |
| 12757 | '\n' |
| 12758 | ' Tuples implement all of the common sequence operations.\n' |
| 12759 | '\n' |
| 12760 | 'For heterogeneous collections of data where access by name is ' |
| 12761 | 'clearer\n' |
| 12762 | 'than access by index, "collections.namedtuple()" may be a more\n' |
| 12763 | 'appropriate choice than a simple tuple object.\n' |
| 12764 | '\n' |
| 12765 | '\n' |
| 12766 | 'Ranges\n' |
| 12767 | '======\n' |
| 12768 | '\n' |
| 12769 | 'The "range" type represents an immutable sequence of numbers and ' |
| 12770 | 'is\n' |
| 12771 | 'commonly used for looping a specific number of times in "for" ' |
| 12772 | 'loops.\n' |
| 12773 | '\n' |
| 12774 | 'class range(stop)\n' |
| 12775 | 'class range(start, stop[, step])\n' |
| 12776 | '\n' |
| 12777 | ' The arguments to the range constructor must be integers ' |
| 12778 | '(either\n' |
| 12779 | ' built-in "int" or any object that implements the "__index__"\n' |
| 12780 | ' special method). If the *step* argument is omitted, it ' |
| 12781 | 'defaults to\n' |
| 12782 | ' "1". If the *start* argument is omitted, it defaults to "0". ' |
| 12783 | 'If\n' |
| 12784 | ' *step* is zero, "ValueError" is raised.\n' |
| 12785 | '\n' |
| 12786 | ' For a positive *step*, the contents of a range "r" are ' |
| 12787 | 'determined\n' |
| 12788 | ' by the formula "r[i] = start + step*i" where "i >= 0" and ' |
| 12789 | '"r[i] <\n' |
| 12790 | ' stop".\n' |
| 12791 | '\n' |
| 12792 | ' For a negative *step*, the contents of the range are still\n' |
| 12793 | ' determined by the formula "r[i] = start + step*i", but the\n' |
| 12794 | ' constraints are "i >= 0" and "r[i] > stop".\n' |
| 12795 | '\n' |
| 12796 | ' A range object will be empty if "r[0]" does not meet the ' |
| 12797 | 'value\n' |
| 12798 | ' constraint. Ranges do support negative indices, but these ' |
| 12799 | 'are\n' |
| 12800 | ' interpreted as indexing from the end of the sequence ' |
| 12801 | 'determined by\n' |
| 12802 | ' the positive indices.\n' |
| 12803 | '\n' |
| 12804 | ' Ranges containing absolute values larger than "sys.maxsize" ' |
| 12805 | 'are\n' |
| 12806 | ' permitted but some features (such as "len()") may raise\n' |
| 12807 | ' "OverflowError".\n' |
| 12808 | '\n' |
| 12809 | ' Range examples:\n' |
| 12810 | '\n' |
| 12811 | ' >>> list(range(10))\n' |
| 12812 | ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n' |
| 12813 | ' >>> list(range(1, 11))\n' |
| 12814 | ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n' |
| 12815 | ' >>> list(range(0, 30, 5))\n' |
| 12816 | ' [0, 5, 10, 15, 20, 25]\n' |
| 12817 | ' >>> list(range(0, 10, 3))\n' |
| 12818 | ' [0, 3, 6, 9]\n' |
| 12819 | ' >>> list(range(0, -10, -1))\n' |
| 12820 | ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n' |
| 12821 | ' >>> list(range(0))\n' |
| 12822 | ' []\n' |
| 12823 | ' >>> list(range(1, 0))\n' |
| 12824 | ' []\n' |
| 12825 | '\n' |
| 12826 | ' Ranges implement all of the common sequence operations ' |
| 12827 | 'except\n' |
| 12828 | ' concatenation and repetition (due to the fact that range ' |
| 12829 | 'objects\n' |
| 12830 | ' can only represent sequences that follow a strict pattern ' |
| 12831 | 'and\n' |
| 12832 | ' repetition and concatenation will usually violate that ' |
| 12833 | 'pattern).\n' |
| 12834 | '\n' |
| 12835 | ' start\n' |
| 12836 | '\n' |
| 12837 | ' The value of the *start* parameter (or "0" if the ' |
| 12838 | 'parameter was\n' |
| 12839 | ' not supplied)\n' |
| 12840 | '\n' |
| 12841 | ' stop\n' |
| 12842 | '\n' |
| 12843 | ' The value of the *stop* parameter\n' |
| 12844 | '\n' |
| 12845 | ' step\n' |
| 12846 | '\n' |
| 12847 | ' The value of the *step* parameter (or "1" if the parameter ' |
| 12848 | 'was\n' |
| 12849 | ' not supplied)\n' |
| 12850 | '\n' |
| 12851 | 'The advantage of the "range" type over a regular "list" or ' |
| 12852 | '"tuple" is\n' |
| 12853 | 'that a "range" object will always take the same (small) amount ' |
| 12854 | 'of\n' |
| 12855 | 'memory, no matter the size of the range it represents (as it ' |
| 12856 | 'only\n' |
| 12857 | 'stores the "start", "stop" and "step" values, calculating ' |
| 12858 | 'individual\n' |
| 12859 | 'items and subranges as needed).\n' |
| 12860 | '\n' |
| 12861 | 'Range objects implement the "collections.abc.Sequence" ABC, and\n' |
| 12862 | 'provide features such as containment tests, element index ' |
| 12863 | 'lookup,\n' |
| 12864 | 'slicing and support for negative indices (see Sequence Types --- ' |
| 12865 | 'list,\n' |
| 12866 | 'tuple, range):\n' |
| 12867 | '\n' |
| 12868 | '>>> r = range(0, 20, 2)\n' |
| 12869 | '>>> r\n' |
| 12870 | 'range(0, 20, 2)\n' |
| 12871 | '>>> 11 in r\n' |
| 12872 | 'False\n' |
| 12873 | '>>> 10 in r\n' |
| 12874 | 'True\n' |
| 12875 | '>>> r.index(10)\n' |
| 12876 | '5\n' |
| 12877 | '>>> r[5]\n' |
| 12878 | '10\n' |
| 12879 | '>>> r[:5]\n' |
| 12880 | 'range(0, 10, 2)\n' |
| 12881 | '>>> r[-1]\n' |
| 12882 | '18\n' |
| 12883 | '\n' |
| 12884 | 'Testing range objects for equality with "==" and "!=" compares ' |
| 12885 | 'them as\n' |
| 12886 | 'sequences. That is, two range objects are considered equal if ' |
| 12887 | 'they\n' |
| 12888 | 'represent the same sequence of values. (Note that two range ' |
| 12889 | 'objects\n' |
| 12890 | 'that compare equal might have different "start", "stop" and ' |
| 12891 | '"step"\n' |
| 12892 | 'attributes, for example "range(0) == range(2, 1, 3)" or ' |
| 12893 | '"range(0, 3,\n' |
| 12894 | '2) == range(0, 4, 2)".)\n' |
| 12895 | '\n' |
| 12896 | 'Changed in version 3.2: Implement the Sequence ABC. Support ' |
| 12897 | 'slicing\n' |
| 12898 | 'and negative indices. Test "int" objects for membership in ' |
| 12899 | 'constant\n' |
| 12900 | 'time instead of iterating through all items.\n' |
| 12901 | '\n' |
| 12902 | "Changed in version 3.3: Define '==' and '!=' to compare range " |
| 12903 | 'objects\n' |
| 12904 | 'based on the sequence of values they define (instead of ' |
| 12905 | 'comparing\n' |
| 12906 | 'based on object identity).\n' |
| 12907 | '\n' |
Ned Deily | c934dde | 2016-09-12 10:48:44 -0400 | [diff] [blame] | 12908 | 'New in version 3.3: The "start", "stop" and "step" attributes.\n' |
| 12909 | '\n' |
| 12910 | 'See also:\n' |
| 12911 | '\n' |
| 12912 | ' * The linspace recipe shows how to implement a lazy version ' |
| 12913 | 'of\n' |
| 12914 | ' range that suitable for floating point applications.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 12915 | 'typesseq-mutable': 'Mutable Sequence Types\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 12916 | '**********************\n' |
| 12917 | '\n' |
| 12918 | 'The operations in the following table are defined on ' |
| 12919 | 'mutable sequence\n' |
| 12920 | 'types. The "collections.abc.MutableSequence" ABC is ' |
| 12921 | 'provided to make\n' |
| 12922 | 'it easier to correctly implement these operations on ' |
| 12923 | 'custom sequence\n' |
| 12924 | 'types.\n' |
| 12925 | '\n' |
| 12926 | 'In the table *s* is an instance of a mutable sequence ' |
| 12927 | 'type, *t* is any\n' |
| 12928 | 'iterable object and *x* is an arbitrary object that ' |
| 12929 | 'meets any type and\n' |
| 12930 | 'value restrictions imposed by *s* (for example, ' |
| 12931 | '"bytearray" only\n' |
| 12932 | 'accepts integers that meet the value restriction "0 <= x ' |
| 12933 | '<= 255").\n' |
| 12934 | '\n' |
| 12935 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12936 | '| Operation | ' |
| 12937 | 'Result | Notes ' |
| 12938 | '|\n' |
| 12939 | '+================================+==================================+=======================+\n' |
| 12940 | '| "s[i] = x" | item *i* of *s* is ' |
| 12941 | 'replaced by | |\n' |
| 12942 | '| | ' |
| 12943 | '*x* | ' |
| 12944 | '|\n' |
| 12945 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12946 | '| "s[i:j] = t" | slice of *s* from *i* ' |
| 12947 | 'to *j* is | |\n' |
| 12948 | '| | replaced by the ' |
| 12949 | 'contents of the | |\n' |
| 12950 | '| | iterable ' |
| 12951 | '*t* | |\n' |
| 12952 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12953 | '| "del s[i:j]" | same as "s[i:j] = ' |
| 12954 | '[]" | |\n' |
| 12955 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12956 | '| "s[i:j:k] = t" | the elements of ' |
| 12957 | '"s[i:j:k]" are | (1) |\n' |
| 12958 | '| | replaced by those of ' |
| 12959 | '*t* | |\n' |
| 12960 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12961 | '| "del s[i:j:k]" | removes the elements ' |
| 12962 | 'of | |\n' |
| 12963 | '| | "s[i:j:k]" from the ' |
| 12964 | 'list | |\n' |
| 12965 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12966 | '| "s.append(x)" | appends *x* to the ' |
| 12967 | 'end of the | |\n' |
| 12968 | '| | sequence (same ' |
| 12969 | 'as | |\n' |
| 12970 | '| | "s[len(s):len(s)] = ' |
| 12971 | '[x]") | |\n' |
| 12972 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12973 | '| "s.clear()" | removes all items ' |
| 12974 | 'from "s" (same | (5) |\n' |
| 12975 | '| | as "del ' |
| 12976 | 's[:]") | |\n' |
| 12977 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12978 | '| "s.copy()" | creates a shallow ' |
| 12979 | 'copy of "s" | (5) |\n' |
| 12980 | '| | (same as ' |
| 12981 | '"s[:]") | |\n' |
| 12982 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12983 | '| "s.extend(t)" or "s += t" | extends *s* with the ' |
| 12984 | 'contents of | |\n' |
| 12985 | '| | *t* (for the most ' |
| 12986 | 'part the same | |\n' |
| 12987 | '| | as "s[len(s):len(s)] ' |
| 12988 | '= t") | |\n' |
| 12989 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12990 | '| "s *= n" | updates *s* with its ' |
| 12991 | 'contents | (6) |\n' |
| 12992 | '| | repeated *n* ' |
| 12993 | 'times | |\n' |
| 12994 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 12995 | '| "s.insert(i, x)" | inserts *x* into *s* ' |
| 12996 | 'at the | |\n' |
| 12997 | '| | index given by *i* ' |
| 12998 | '(same as | |\n' |
| 12999 | '| | "s[i:i] = ' |
| 13000 | '[x]") | |\n' |
| 13001 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13002 | '| "s.pop([i])" | retrieves the item at ' |
| 13003 | '*i* and | (2) |\n' |
| 13004 | '| | also removes it from ' |
| 13005 | '*s* | |\n' |
| 13006 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13007 | '| "s.remove(x)" | remove the first item ' |
| 13008 | 'from *s* | (3) |\n' |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13009 | '| | where "s[i]" is equal ' |
| 13010 | 'to *x* | |\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13011 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13012 | '| "s.reverse()" | reverses the items of ' |
| 13013 | '*s* in | (4) |\n' |
| 13014 | '| | ' |
| 13015 | 'place | ' |
| 13016 | '|\n' |
| 13017 | '+--------------------------------+----------------------------------+-----------------------+\n' |
| 13018 | '\n' |
| 13019 | 'Notes:\n' |
| 13020 | '\n' |
| 13021 | '1. *t* must have the same length as the slice it is ' |
| 13022 | 'replacing.\n' |
| 13023 | '\n' |
| 13024 | '2. The optional argument *i* defaults to "-1", so that ' |
| 13025 | 'by default\n' |
| 13026 | ' the last item is removed and returned.\n' |
| 13027 | '\n' |
| 13028 | '3. "remove" raises "ValueError" when *x* is not found in ' |
| 13029 | '*s*.\n' |
| 13030 | '\n' |
| 13031 | '4. The "reverse()" method modifies the sequence in place ' |
| 13032 | 'for\n' |
| 13033 | ' economy of space when reversing a large sequence. To ' |
| 13034 | 'remind users\n' |
| 13035 | ' that it operates by side effect, it does not return ' |
| 13036 | 'the reversed\n' |
| 13037 | ' sequence.\n' |
| 13038 | '\n' |
| 13039 | '5. "clear()" and "copy()" are included for consistency ' |
| 13040 | 'with the\n' |
| 13041 | " interfaces of mutable containers that don't support " |
| 13042 | 'slicing\n' |
| 13043 | ' operations (such as "dict" and "set")\n' |
| 13044 | '\n' |
| 13045 | ' New in version 3.3: "clear()" and "copy()" methods.\n' |
| 13046 | '\n' |
| 13047 | '6. The value *n* is an integer, or an object ' |
| 13048 | 'implementing\n' |
| 13049 | ' "__index__()". Zero and negative values of *n* clear ' |
| 13050 | 'the sequence.\n' |
| 13051 | ' Items in the sequence are not copied; they are ' |
| 13052 | 'referenced multiple\n' |
| 13053 | ' times, as explained for "s * n" under Common Sequence ' |
| 13054 | 'Operations.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13055 | 'unary': 'Unary arithmetic and bitwise operations\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13056 | '***************************************\n' |
| 13057 | '\n' |
| 13058 | 'All unary arithmetic and bitwise operations have the same ' |
| 13059 | 'priority:\n' |
| 13060 | '\n' |
| 13061 | ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n' |
| 13062 | '\n' |
| 13063 | 'The unary "-" (minus) operator yields the negation of its numeric\n' |
| 13064 | 'argument.\n' |
| 13065 | '\n' |
| 13066 | 'The unary "+" (plus) operator yields its numeric argument ' |
| 13067 | 'unchanged.\n' |
| 13068 | '\n' |
| 13069 | 'The unary "~" (invert) operator yields the bitwise inversion of ' |
| 13070 | 'its\n' |
| 13071 | 'integer argument. The bitwise inversion of "x" is defined as\n' |
| 13072 | '"-(x+1)". It only applies to integral numbers.\n' |
| 13073 | '\n' |
| 13074 | 'In all three cases, if the argument does not have the proper type, ' |
| 13075 | 'a\n' |
| 13076 | '"TypeError" exception is raised.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13077 | 'while': 'The "while" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13078 | '*********************\n' |
| 13079 | '\n' |
| 13080 | 'The "while" statement is used for repeated execution as long as an\n' |
| 13081 | 'expression is true:\n' |
| 13082 | '\n' |
| 13083 | ' while_stmt ::= "while" expression ":" suite\n' |
| 13084 | ' ["else" ":" suite]\n' |
| 13085 | '\n' |
| 13086 | 'This repeatedly tests the expression and, if it is true, executes ' |
| 13087 | 'the\n' |
| 13088 | 'first suite; if the expression is false (which may be the first ' |
| 13089 | 'time\n' |
| 13090 | 'it is tested) the suite of the "else" clause, if present, is ' |
| 13091 | 'executed\n' |
| 13092 | 'and the loop terminates.\n' |
| 13093 | '\n' |
| 13094 | 'A "break" statement executed in the first suite terminates the ' |
| 13095 | 'loop\n' |
| 13096 | 'without executing the "else" clause\'s suite. A "continue" ' |
| 13097 | 'statement\n' |
| 13098 | 'executed in the first suite skips the rest of the suite and goes ' |
| 13099 | 'back\n' |
| 13100 | 'to testing the expression.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13101 | 'with': 'The "with" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13102 | '********************\n' |
| 13103 | '\n' |
| 13104 | 'The "with" statement is used to wrap the execution of a block with\n' |
| 13105 | 'methods defined by a context manager (see section With Statement\n' |
| 13106 | 'Context Managers). This allows common "try"..."except"..."finally"\n' |
| 13107 | 'usage patterns to be encapsulated for convenient reuse.\n' |
| 13108 | '\n' |
| 13109 | ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' |
| 13110 | ' with_item ::= expression ["as" target]\n' |
| 13111 | '\n' |
| 13112 | 'The execution of the "with" statement with one "item" proceeds as\n' |
| 13113 | 'follows:\n' |
| 13114 | '\n' |
| 13115 | '1. The context expression (the expression given in the "with_item")\n' |
| 13116 | ' is evaluated to obtain a context manager.\n' |
| 13117 | '\n' |
| 13118 | '2. The context manager\'s "__exit__()" is loaded for later use.\n' |
| 13119 | '\n' |
| 13120 | '3. The context manager\'s "__enter__()" method is invoked.\n' |
| 13121 | '\n' |
| 13122 | '4. If a target was included in the "with" statement, the return\n' |
| 13123 | ' value from "__enter__()" is assigned to it.\n' |
| 13124 | '\n' |
| 13125 | ' Note: The "with" statement guarantees that if the "__enter__()"\n' |
| 13126 | ' method returns without an error, then "__exit__()" will always ' |
| 13127 | 'be\n' |
| 13128 | ' called. Thus, if an error occurs during the assignment to the\n' |
| 13129 | ' target list, it will be treated the same as an error occurring\n' |
| 13130 | ' within the suite would be. See step 6 below.\n' |
| 13131 | '\n' |
| 13132 | '5. The suite is executed.\n' |
| 13133 | '\n' |
| 13134 | '6. The context manager\'s "__exit__()" method is invoked. If an\n' |
| 13135 | ' exception caused the suite to be exited, its type, value, and\n' |
| 13136 | ' traceback are passed as arguments to "__exit__()". Otherwise, ' |
| 13137 | 'three\n' |
| 13138 | ' "None" arguments are supplied.\n' |
| 13139 | '\n' |
| 13140 | ' If the suite was exited due to an exception, and the return ' |
| 13141 | 'value\n' |
| 13142 | ' from the "__exit__()" method was false, the exception is ' |
| 13143 | 'reraised.\n' |
| 13144 | ' If the return value was true, the exception is suppressed, and\n' |
| 13145 | ' execution continues with the statement following the "with"\n' |
| 13146 | ' statement.\n' |
| 13147 | '\n' |
| 13148 | ' If the suite was exited for any reason other than an exception, ' |
| 13149 | 'the\n' |
| 13150 | ' return value from "__exit__()" is ignored, and execution ' |
| 13151 | 'proceeds\n' |
| 13152 | ' at the normal location for the kind of exit that was taken.\n' |
| 13153 | '\n' |
| 13154 | 'With more than one item, the context managers are processed as if\n' |
| 13155 | 'multiple "with" statements were nested:\n' |
| 13156 | '\n' |
| 13157 | ' with A() as a, B() as b:\n' |
| 13158 | ' suite\n' |
| 13159 | '\n' |
| 13160 | 'is equivalent to\n' |
| 13161 | '\n' |
| 13162 | ' with A() as a:\n' |
| 13163 | ' with B() as b:\n' |
| 13164 | ' suite\n' |
| 13165 | '\n' |
| 13166 | 'Changed in version 3.1: Support for multiple context expressions.\n' |
| 13167 | '\n' |
| 13168 | 'See also:\n' |
| 13169 | '\n' |
| 13170 | ' **PEP 343** - The "with" statement\n' |
| 13171 | ' The specification, background, and examples for the Python ' |
| 13172 | '"with"\n' |
| 13173 | ' statement.\n', |
Ned Deily | 450ceea | 2017-09-19 01:01:36 -0400 | [diff] [blame] | 13174 | 'yield': 'The "yield" statement\n' |
Ned Deily | cae752a | 2016-05-16 13:44:52 -0400 | [diff] [blame] | 13175 | '*********************\n' |
| 13176 | '\n' |
| 13177 | ' yield_stmt ::= yield_expression\n' |
| 13178 | '\n' |
| 13179 | 'A "yield" statement is semantically equivalent to a yield ' |
| 13180 | 'expression.\n' |
| 13181 | 'The yield statement can be used to omit the parentheses that would\n' |
| 13182 | 'otherwise be required in the equivalent yield expression ' |
| 13183 | 'statement.\n' |
| 13184 | 'For example, the yield statements\n' |
| 13185 | '\n' |
| 13186 | ' yield <expr>\n' |
| 13187 | ' yield from <expr>\n' |
| 13188 | '\n' |
| 13189 | 'are equivalent to the yield expression statements\n' |
| 13190 | '\n' |
| 13191 | ' (yield <expr>)\n' |
| 13192 | ' (yield from <expr>)\n' |
| 13193 | '\n' |
| 13194 | 'Yield expressions and statements are only used when defining a\n' |
| 13195 | '*generator* function, and are only used in the body of the ' |
| 13196 | 'generator\n' |
| 13197 | 'function. Using yield in a function definition is sufficient to ' |
| 13198 | 'cause\n' |
| 13199 | 'that definition to create a generator function instead of a normal\n' |
| 13200 | 'function.\n' |
| 13201 | '\n' |
| 13202 | 'For full details of "yield" semantics, refer to the Yield ' |
| 13203 | 'expressions\n' |
| 13204 | 'section.\n'} |