Mercurial > repos > rliterman > csp2
comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/pydoc_data/topics.py @ 69:33d812a61356
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
| author | jpayne |
|---|---|
| date | Tue, 18 Mar 2025 17:55:14 -0400 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 67:0e9998148a16 | 69:33d812a61356 |
|---|---|
| 1 # -*- coding: utf-8 -*- | |
| 2 # Autogenerated by Sphinx on Wed Dec 18 18:17:58 2019 | |
| 3 topics = {'assert': 'The "assert" statement\n' | |
| 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 ' | |
| 30 'an\n' | |
| 31 'assert statement when optimization is requested at compile time. ' | |
| 32 'Note\n' | |
| 33 'that it is unnecessary to include the source code for the ' | |
| 34 'expression\n' | |
| 35 'that failed in the error message; it will be displayed as part of ' | |
| 36 'the\n' | |
| 37 'stack trace.\n' | |
| 38 '\n' | |
| 39 'Assignments to "__debug__" are illegal. The value for the ' | |
| 40 'built-in\n' | |
| 41 'variable is determined when the interpreter starts.\n', | |
| 42 'assignment': 'Assignment statements\n' | |
| 43 '*********************\n' | |
| 44 '\n' | |
| 45 'Assignment statements are used to (re)bind names to values and ' | |
| 46 'to\n' | |
| 47 'modify attributes or items of mutable objects:\n' | |
| 48 '\n' | |
| 49 ' assignment_stmt ::= (target_list "=")+ (starred_expression ' | |
| 50 '| yield_expression)\n' | |
| 51 ' target_list ::= target ("," target)* [","]\n' | |
| 52 ' target ::= identifier\n' | |
| 53 ' | "(" [target_list] ")"\n' | |
| 54 ' | "[" [target_list] "]"\n' | |
| 55 ' | attributeref\n' | |
| 56 ' | subscription\n' | |
| 57 ' | slicing\n' | |
| 58 ' | "*" target\n' | |
| 59 '\n' | |
| 60 '(See section Primaries for the syntax definitions for ' | |
| 61 '*attributeref*,\n' | |
| 62 '*subscription*, and *slicing*.)\n' | |
| 63 '\n' | |
| 64 'An assignment statement evaluates the expression list ' | |
| 65 '(remember that\n' | |
| 66 'this can be a single expression or a comma-separated list, the ' | |
| 67 'latter\n' | |
| 68 'yielding a tuple) and assigns the single resulting object to ' | |
| 69 'each of\n' | |
| 70 'the target lists, from left to right.\n' | |
| 71 '\n' | |
| 72 'Assignment is defined recursively depending on the form of the ' | |
| 73 'target\n' | |
| 74 '(list). When a target is part of a mutable object (an ' | |
| 75 'attribute\n' | |
| 76 'reference, subscription or slicing), the mutable object must\n' | |
| 77 'ultimately perform the assignment and decide about its ' | |
| 78 'validity, and\n' | |
| 79 'may raise an exception if the assignment is unacceptable. The ' | |
| 80 'rules\n' | |
| 81 'observed by various types and the exceptions raised are given ' | |
| 82 'with the\n' | |
| 83 'definition of the object types (see section The standard type\n' | |
| 84 'hierarchy).\n' | |
| 85 '\n' | |
| 86 'Assignment of an object to a target list, optionally enclosed ' | |
| 87 'in\n' | |
| 88 'parentheses or square brackets, is recursively defined as ' | |
| 89 'follows.\n' | |
| 90 '\n' | |
| 91 '* If the target list is a single target with no trailing ' | |
| 92 'comma,\n' | |
| 93 ' optionally in parentheses, the object is assigned to that ' | |
| 94 'target.\n' | |
| 95 '\n' | |
| 96 '* Else: The object must be an iterable with the same number of ' | |
| 97 'items\n' | |
| 98 ' as there are targets in the target list, and the items are ' | |
| 99 'assigned,\n' | |
| 100 ' from left to right, to the corresponding targets.\n' | |
| 101 '\n' | |
| 102 ' * If the target list contains one target prefixed with an\n' | |
| 103 ' asterisk, called a “starred” target: The object must be ' | |
| 104 'an\n' | |
| 105 ' iterable with at least as many items as there are targets ' | |
| 106 'in the\n' | |
| 107 ' target list, minus one. The first items of the iterable ' | |
| 108 'are\n' | |
| 109 ' assigned, from left to right, to the targets before the ' | |
| 110 'starred\n' | |
| 111 ' target. The final items of the iterable are assigned to ' | |
| 112 'the\n' | |
| 113 ' targets after the starred target. A list of the remaining ' | |
| 114 'items\n' | |
| 115 ' in the iterable is then assigned to the starred target ' | |
| 116 '(the list\n' | |
| 117 ' can be empty).\n' | |
| 118 '\n' | |
| 119 ' * Else: The object must be an iterable with the same number ' | |
| 120 'of\n' | |
| 121 ' items as there are targets in the target list, and the ' | |
| 122 'items are\n' | |
| 123 ' assigned, from left to right, to the corresponding ' | |
| 124 'targets.\n' | |
| 125 '\n' | |
| 126 'Assignment of an object to a single target is recursively ' | |
| 127 'defined as\n' | |
| 128 'follows.\n' | |
| 129 '\n' | |
| 130 '* If the target is an identifier (name):\n' | |
| 131 '\n' | |
| 132 ' * If the name does not occur in a "global" or "nonlocal" ' | |
| 133 'statement\n' | |
| 134 ' in the current code block: the name is bound to the object ' | |
| 135 'in the\n' | |
| 136 ' current local namespace.\n' | |
| 137 '\n' | |
| 138 ' * Otherwise: the name is bound to the object in the global\n' | |
| 139 ' namespace or the outer namespace determined by ' | |
| 140 '"nonlocal",\n' | |
| 141 ' respectively.\n' | |
| 142 '\n' | |
| 143 ' The name is rebound if it was already bound. This may cause ' | |
| 144 'the\n' | |
| 145 ' reference count for the object previously bound to the name ' | |
| 146 'to reach\n' | |
| 147 ' zero, causing the object to be deallocated and its ' | |
| 148 'destructor (if it\n' | |
| 149 ' has one) to be called.\n' | |
| 150 '\n' | |
| 151 '* If the target is an attribute reference: The primary ' | |
| 152 'expression in\n' | |
| 153 ' the reference is evaluated. It should yield an object with\n' | |
| 154 ' assignable attributes; if this is not the case, "TypeError" ' | |
| 155 'is\n' | |
| 156 ' raised. That object is then asked to assign the assigned ' | |
| 157 'object to\n' | |
| 158 ' the given attribute; if it cannot perform the assignment, it ' | |
| 159 'raises\n' | |
| 160 ' an exception (usually but not necessarily ' | |
| 161 '"AttributeError").\n' | |
| 162 '\n' | |
| 163 ' Note: If the object is a class instance and the attribute ' | |
| 164 'reference\n' | |
| 165 ' occurs on both sides of the assignment operator, the ' | |
| 166 'right-hand side\n' | |
| 167 ' expression, "a.x" can access either an instance attribute or ' | |
| 168 '(if no\n' | |
| 169 ' instance attribute exists) a class attribute. The left-hand ' | |
| 170 'side\n' | |
| 171 ' target "a.x" is always set as an instance attribute, ' | |
| 172 'creating it if\n' | |
| 173 ' necessary. Thus, the two occurrences of "a.x" do not ' | |
| 174 'necessarily\n' | |
| 175 ' refer to the same attribute: if the right-hand side ' | |
| 176 'expression\n' | |
| 177 ' refers to a class attribute, the left-hand side creates a ' | |
| 178 'new\n' | |
| 179 ' instance attribute as the target of the assignment:\n' | |
| 180 '\n' | |
| 181 ' class Cls:\n' | |
| 182 ' x = 3 # class variable\n' | |
| 183 ' inst = Cls()\n' | |
| 184 ' inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x ' | |
| 185 'as 3\n' | |
| 186 '\n' | |
| 187 ' This description does not necessarily apply to descriptor\n' | |
| 188 ' attributes, such as properties created with "property()".\n' | |
| 189 '\n' | |
| 190 '* If the target is a subscription: The primary expression in ' | |
| 191 'the\n' | |
| 192 ' reference is evaluated. It should yield either a mutable ' | |
| 193 'sequence\n' | |
| 194 ' object (such as a list) or a mapping object (such as a ' | |
| 195 'dictionary).\n' | |
| 196 ' Next, the subscript expression is evaluated.\n' | |
| 197 '\n' | |
| 198 ' If the primary is a mutable sequence object (such as a ' | |
| 199 'list), the\n' | |
| 200 ' subscript must yield an integer. If it is negative, the ' | |
| 201 'sequence’s\n' | |
| 202 ' length is added to it. The resulting value must be a ' | |
| 203 'nonnegative\n' | |
| 204 ' integer less than the sequence’s length, and the sequence is ' | |
| 205 'asked\n' | |
| 206 ' to assign the assigned object to its item with that index. ' | |
| 207 'If the\n' | |
| 208 ' index is out of range, "IndexError" is raised (assignment to ' | |
| 209 'a\n' | |
| 210 ' subscripted sequence cannot add new items to a list).\n' | |
| 211 '\n' | |
| 212 ' If the primary is a mapping object (such as a dictionary), ' | |
| 213 'the\n' | |
| 214 ' subscript must have a type compatible with the mapping’s key ' | |
| 215 'type,\n' | |
| 216 ' and the mapping is then asked to create a key/datum pair ' | |
| 217 'which maps\n' | |
| 218 ' the subscript to the assigned object. This can either ' | |
| 219 'replace an\n' | |
| 220 ' existing key/value pair with the same key value, or insert a ' | |
| 221 'new\n' | |
| 222 ' key/value pair (if no key with the same value existed).\n' | |
| 223 '\n' | |
| 224 ' For user-defined objects, the "__setitem__()" method is ' | |
| 225 'called with\n' | |
| 226 ' appropriate arguments.\n' | |
| 227 '\n' | |
| 228 '* If the target is a slicing: The primary expression in the\n' | |
| 229 ' reference is evaluated. It should yield a mutable sequence ' | |
| 230 'object\n' | |
| 231 ' (such as a list). The assigned object should be a sequence ' | |
| 232 'object\n' | |
| 233 ' of the same type. Next, the lower and upper bound ' | |
| 234 'expressions are\n' | |
| 235 ' evaluated, insofar they are present; defaults are zero and ' | |
| 236 'the\n' | |
| 237 ' sequence’s length. The bounds should evaluate to integers. ' | |
| 238 'If\n' | |
| 239 ' either bound is negative, the sequence’s length is added to ' | |
| 240 'it. The\n' | |
| 241 ' resulting bounds are clipped to lie between zero and the ' | |
| 242 'sequence’s\n' | |
| 243 ' length, inclusive. Finally, the sequence object is asked to ' | |
| 244 'replace\n' | |
| 245 ' the slice with the items of the assigned sequence. The ' | |
| 246 'length of\n' | |
| 247 ' the slice may be different from the length of the assigned ' | |
| 248 'sequence,\n' | |
| 249 ' thus changing the length of the target sequence, if the ' | |
| 250 'target\n' | |
| 251 ' sequence allows it.\n' | |
| 252 '\n' | |
| 253 '**CPython implementation detail:** In the current ' | |
| 254 'implementation, the\n' | |
| 255 'syntax for targets is taken to be the same as for expressions, ' | |
| 256 'and\n' | |
| 257 'invalid syntax is rejected during the code generation phase, ' | |
| 258 'causing\n' | |
| 259 'less detailed error messages.\n' | |
| 260 '\n' | |
| 261 'Although the definition of assignment implies that overlaps ' | |
| 262 'between\n' | |
| 263 'the left-hand side and the right-hand side are ‘simultaneous’ ' | |
| 264 '(for\n' | |
| 265 'example "a, b = b, a" swaps two variables), overlaps *within* ' | |
| 266 'the\n' | |
| 267 'collection of assigned-to variables occur left-to-right, ' | |
| 268 'sometimes\n' | |
| 269 'resulting in confusion. For instance, the following program ' | |
| 270 'prints\n' | |
| 271 '"[0, 2]":\n' | |
| 272 '\n' | |
| 273 ' x = [0, 1]\n' | |
| 274 ' i = 0\n' | |
| 275 ' i, x[i] = 1, 2 # i is updated, then x[i] is ' | |
| 276 'updated\n' | |
| 277 ' print(x)\n' | |
| 278 '\n' | |
| 279 'See also:\n' | |
| 280 '\n' | |
| 281 ' **PEP 3132** - Extended Iterable Unpacking\n' | |
| 282 ' The specification for the "*target" feature.\n' | |
| 283 '\n' | |
| 284 '\n' | |
| 285 'Augmented assignment statements\n' | |
| 286 '===============================\n' | |
| 287 '\n' | |
| 288 'Augmented assignment is the combination, in a single ' | |
| 289 'statement, of a\n' | |
| 290 'binary operation and an assignment statement:\n' | |
| 291 '\n' | |
| 292 ' augmented_assignment_stmt ::= augtarget augop ' | |
| 293 '(expression_list | yield_expression)\n' | |
| 294 ' augtarget ::= identifier | attributeref | ' | |
| 295 'subscription | slicing\n' | |
| 296 ' augop ::= "+=" | "-=" | "*=" | "@=" | ' | |
| 297 '"/=" | "//=" | "%=" | "**="\n' | |
| 298 ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' | |
| 299 '\n' | |
| 300 '(See section Primaries for the syntax definitions of the last ' | |
| 301 'three\n' | |
| 302 'symbols.)\n' | |
| 303 '\n' | |
| 304 'An augmented assignment evaluates the target (which, unlike ' | |
| 305 'normal\n' | |
| 306 'assignment statements, cannot be an unpacking) and the ' | |
| 307 'expression\n' | |
| 308 'list, performs the binary operation specific to the type of ' | |
| 309 'assignment\n' | |
| 310 'on the two operands, and assigns the result to the original ' | |
| 311 'target.\n' | |
| 312 'The target is only evaluated once.\n' | |
| 313 '\n' | |
| 314 'An augmented assignment expression like "x += 1" can be ' | |
| 315 'rewritten as\n' | |
| 316 '"x = x + 1" to achieve a similar, but not exactly equal ' | |
| 317 'effect. In the\n' | |
| 318 'augmented version, "x" is only evaluated once. Also, when ' | |
| 319 'possible,\n' | |
| 320 'the actual operation is performed *in-place*, meaning that ' | |
| 321 'rather than\n' | |
| 322 'creating a new object and assigning that to the target, the ' | |
| 323 'old object\n' | |
| 324 'is modified instead.\n' | |
| 325 '\n' | |
| 326 'Unlike normal assignments, augmented assignments evaluate the ' | |
| 327 'left-\n' | |
| 328 'hand side *before* evaluating the right-hand side. For ' | |
| 329 'example, "a[i]\n' | |
| 330 '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' | |
| 331 'performs\n' | |
| 332 'the addition, and lastly, it writes the result back to ' | |
| 333 '"a[i]".\n' | |
| 334 '\n' | |
| 335 'With the exception of assigning to tuples and multiple targets ' | |
| 336 'in a\n' | |
| 337 'single statement, the assignment done by augmented assignment\n' | |
| 338 'statements is handled the same way as normal assignments. ' | |
| 339 'Similarly,\n' | |
| 340 'with the exception of the possible *in-place* behavior, the ' | |
| 341 'binary\n' | |
| 342 'operation performed by augmented assignment is the same as the ' | |
| 343 'normal\n' | |
| 344 'binary operations.\n' | |
| 345 '\n' | |
| 346 'For targets which are attribute references, the same caveat ' | |
| 347 'about\n' | |
| 348 'class and instance attributes applies as for regular ' | |
| 349 'assignments.\n' | |
| 350 '\n' | |
| 351 '\n' | |
| 352 'Annotated assignment statements\n' | |
| 353 '===============================\n' | |
| 354 '\n' | |
| 355 '*Annotation* assignment is the combination, in a single ' | |
| 356 'statement, of\n' | |
| 357 'a variable or attribute annotation and an optional assignment\n' | |
| 358 'statement:\n' | |
| 359 '\n' | |
| 360 ' annotated_assignment_stmt ::= augtarget ":" expression\n' | |
| 361 ' ["=" (starred_expression | ' | |
| 362 'yield_expression)]\n' | |
| 363 '\n' | |
| 364 'The difference from normal Assignment statements is that only ' | |
| 365 'single\n' | |
| 366 'target is allowed.\n' | |
| 367 '\n' | |
| 368 'For simple names as assignment targets, if in class or module ' | |
| 369 'scope,\n' | |
| 370 'the annotations are evaluated and stored in a special class or ' | |
| 371 'module\n' | |
| 372 'attribute "__annotations__" that is a dictionary mapping from ' | |
| 373 'variable\n' | |
| 374 'names (mangled if private) to evaluated annotations. This ' | |
| 375 'attribute is\n' | |
| 376 'writable and is automatically created at the start of class or ' | |
| 377 'module\n' | |
| 378 'body execution, if annotations are found statically.\n' | |
| 379 '\n' | |
| 380 'For expressions as assignment targets, the annotations are ' | |
| 381 'evaluated\n' | |
| 382 'if in class or module scope, but not stored.\n' | |
| 383 '\n' | |
| 384 'If a name is annotated in a function scope, then this name is ' | |
| 385 'local\n' | |
| 386 'for that scope. Annotations are never evaluated and stored in ' | |
| 387 'function\n' | |
| 388 'scopes.\n' | |
| 389 '\n' | |
| 390 'If the right hand side is present, an annotated assignment ' | |
| 391 'performs\n' | |
| 392 'the actual assignment before evaluating annotations (where\n' | |
| 393 'applicable). If the right hand side is not present for an ' | |
| 394 'expression\n' | |
| 395 'target, then the interpreter evaluates the target except for ' | |
| 396 'the last\n' | |
| 397 '"__setitem__()" or "__setattr__()" call.\n' | |
| 398 '\n' | |
| 399 'See also:\n' | |
| 400 '\n' | |
| 401 ' **PEP 526** - Syntax for Variable Annotations\n' | |
| 402 ' The proposal that added syntax for annotating the types ' | |
| 403 'of\n' | |
| 404 ' variables (including class variables and instance ' | |
| 405 'variables),\n' | |
| 406 ' instead of expressing them through comments.\n' | |
| 407 '\n' | |
| 408 ' **PEP 484** - Type hints\n' | |
| 409 ' The proposal that added the "typing" module to provide a ' | |
| 410 'standard\n' | |
| 411 ' syntax for type annotations that can be used in static ' | |
| 412 'analysis\n' | |
| 413 ' tools and IDEs.\n' | |
| 414 '\n' | |
| 415 'Changed in version 3.8: Now annotated assignments allow same\n' | |
| 416 'expressions in the right hand side as the regular ' | |
| 417 'assignments.\n' | |
| 418 'Previously, some expressions (like un-parenthesized tuple ' | |
| 419 'expressions)\n' | |
| 420 'caused a syntax error.\n', | |
| 421 'async': 'Coroutines\n' | |
| 422 '**********\n' | |
| 423 '\n' | |
| 424 'New in version 3.5.\n' | |
| 425 '\n' | |
| 426 '\n' | |
| 427 'Coroutine function definition\n' | |
| 428 '=============================\n' | |
| 429 '\n' | |
| 430 ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' | |
| 431 '[parameter_list] ")"\n' | |
| 432 ' ["->" expression] ":" suite\n' | |
| 433 '\n' | |
| 434 'Execution of Python coroutines can be suspended and resumed at ' | |
| 435 'many\n' | |
| 436 'points (see *coroutine*). Inside the body of a coroutine ' | |
| 437 'function,\n' | |
| 438 '"await" and "async" identifiers become reserved keywords; "await"\n' | |
| 439 'expressions, "async for" and "async with" can only be used in\n' | |
| 440 'coroutine function bodies.\n' | |
| 441 '\n' | |
| 442 'Functions defined with "async def" syntax are always coroutine\n' | |
| 443 'functions, even if they do not contain "await" or "async" ' | |
| 444 'keywords.\n' | |
| 445 '\n' | |
| 446 'It is a "SyntaxError" to use a "yield from" expression inside the ' | |
| 447 'body\n' | |
| 448 'of a coroutine function.\n' | |
| 449 '\n' | |
| 450 'An example of a coroutine function:\n' | |
| 451 '\n' | |
| 452 ' async def func(param1, param2):\n' | |
| 453 ' do_stuff()\n' | |
| 454 ' await some_coroutine()\n' | |
| 455 '\n' | |
| 456 '\n' | |
| 457 'The "async for" statement\n' | |
| 458 '=========================\n' | |
| 459 '\n' | |
| 460 ' async_for_stmt ::= "async" for_stmt\n' | |
| 461 '\n' | |
| 462 'An *asynchronous iterable* is able to call asynchronous code in ' | |
| 463 'its\n' | |
| 464 '*iter* implementation, and *asynchronous iterator* can call\n' | |
| 465 'asynchronous code in its *next* method.\n' | |
| 466 '\n' | |
| 467 'The "async for" statement allows convenient iteration over\n' | |
| 468 'asynchronous iterators.\n' | |
| 469 '\n' | |
| 470 'The following code:\n' | |
| 471 '\n' | |
| 472 ' async for TARGET in ITER:\n' | |
| 473 ' BLOCK\n' | |
| 474 ' else:\n' | |
| 475 ' BLOCK2\n' | |
| 476 '\n' | |
| 477 'Is semantically equivalent to:\n' | |
| 478 '\n' | |
| 479 ' iter = (ITER)\n' | |
| 480 ' iter = type(iter).__aiter__(iter)\n' | |
| 481 ' running = True\n' | |
| 482 ' while running:\n' | |
| 483 ' try:\n' | |
| 484 ' TARGET = await type(iter).__anext__(iter)\n' | |
| 485 ' except StopAsyncIteration:\n' | |
| 486 ' running = False\n' | |
| 487 ' else:\n' | |
| 488 ' BLOCK\n' | |
| 489 ' else:\n' | |
| 490 ' BLOCK2\n' | |
| 491 '\n' | |
| 492 'See also "__aiter__()" and "__anext__()" for details.\n' | |
| 493 '\n' | |
| 494 'It is a "SyntaxError" to use an "async for" statement outside the ' | |
| 495 'body\n' | |
| 496 'of a coroutine function.\n' | |
| 497 '\n' | |
| 498 '\n' | |
| 499 'The "async with" statement\n' | |
| 500 '==========================\n' | |
| 501 '\n' | |
| 502 ' async_with_stmt ::= "async" with_stmt\n' | |
| 503 '\n' | |
| 504 'An *asynchronous context manager* is a *context manager* that is ' | |
| 505 'able\n' | |
| 506 'to suspend execution in its *enter* and *exit* methods.\n' | |
| 507 '\n' | |
| 508 'The following code:\n' | |
| 509 '\n' | |
| 510 ' async with EXPR as VAR:\n' | |
| 511 ' BLOCK\n' | |
| 512 '\n' | |
| 513 'Is semantically equivalent to:\n' | |
| 514 '\n' | |
| 515 ' mgr = (EXPR)\n' | |
| 516 ' aexit = type(mgr).__aexit__\n' | |
| 517 ' aenter = type(mgr).__aenter__(mgr)\n' | |
| 518 '\n' | |
| 519 ' VAR = await aenter\n' | |
| 520 ' try:\n' | |
| 521 ' BLOCK\n' | |
| 522 ' except:\n' | |
| 523 ' if not await aexit(mgr, *sys.exc_info()):\n' | |
| 524 ' raise\n' | |
| 525 ' else:\n' | |
| 526 ' await aexit(mgr, None, None, None)\n' | |
| 527 '\n' | |
| 528 'See also "__aenter__()" and "__aexit__()" for details.\n' | |
| 529 '\n' | |
| 530 'It is a "SyntaxError" to use an "async with" statement outside the\n' | |
| 531 'body of a coroutine function.\n' | |
| 532 '\n' | |
| 533 'See also:\n' | |
| 534 '\n' | |
| 535 ' **PEP 492** - Coroutines with async and await syntax\n' | |
| 536 ' The proposal that made coroutines a proper standalone concept ' | |
| 537 'in\n' | |
| 538 ' Python, and added supporting syntax.\n' | |
| 539 '\n' | |
| 540 '-[ Footnotes ]-\n' | |
| 541 '\n' | |
| 542 '[1] The exception is propagated to the invocation stack unless\n' | |
| 543 ' there is a "finally" clause which happens to raise another\n' | |
| 544 ' exception. That new exception causes the old one to be lost.\n' | |
| 545 '\n' | |
| 546 '[2] A string literal appearing as the first statement in the\n' | |
| 547 ' function body is transformed into the function’s "__doc__"\n' | |
| 548 ' attribute and therefore the function’s *docstring*.\n' | |
| 549 '\n' | |
| 550 '[3] A string literal appearing as the first statement in the class\n' | |
| 551 ' body is transformed into the namespace’s "__doc__" item and\n' | |
| 552 ' therefore the class’s *docstring*.\n', | |
| 553 'atom-identifiers': 'Identifiers (Names)\n' | |
| 554 '*******************\n' | |
| 555 '\n' | |
| 556 'An identifier occurring as an atom is a name. See ' | |
| 557 'section Identifiers\n' | |
| 558 'and keywords for lexical definition and section Naming ' | |
| 559 'and binding for\n' | |
| 560 'documentation of naming and binding.\n' | |
| 561 '\n' | |
| 562 'When the name is bound to an object, evaluation of the ' | |
| 563 'atom yields\n' | |
| 564 'that object. When a name is not bound, an attempt to ' | |
| 565 'evaluate it\n' | |
| 566 'raises a "NameError" exception.\n' | |
| 567 '\n' | |
| 568 '**Private name mangling:** When an identifier that ' | |
| 569 'textually occurs in\n' | |
| 570 'a class definition begins with two or more underscore ' | |
| 571 'characters and\n' | |
| 572 'does not end in two or more underscores, it is ' | |
| 573 'considered a *private\n' | |
| 574 'name* of that class. Private names are transformed to a ' | |
| 575 'longer form\n' | |
| 576 'before code is generated for them. The transformation ' | |
| 577 'inserts the\n' | |
| 578 'class name, with leading underscores removed and a ' | |
| 579 'single underscore\n' | |
| 580 'inserted, in front of the name. For example, the ' | |
| 581 'identifier "__spam"\n' | |
| 582 'occurring in a class named "Ham" will be transformed to ' | |
| 583 '"_Ham__spam".\n' | |
| 584 'This transformation is independent of the syntactical ' | |
| 585 'context in which\n' | |
| 586 'the identifier is used. If the transformed name is ' | |
| 587 'extremely long\n' | |
| 588 '(longer than 255 characters), implementation defined ' | |
| 589 'truncation may\n' | |
| 590 'happen. If the class name consists only of underscores, ' | |
| 591 'no\n' | |
| 592 'transformation is done.\n', | |
| 593 'atom-literals': 'Literals\n' | |
| 594 '********\n' | |
| 595 '\n' | |
| 596 'Python supports string and bytes literals and various ' | |
| 597 'numeric\n' | |
| 598 'literals:\n' | |
| 599 '\n' | |
| 600 ' literal ::= stringliteral | bytesliteral\n' | |
| 601 ' | integer | floatnumber | imagnumber\n' | |
| 602 '\n' | |
| 603 'Evaluation of a literal yields an object of the given type ' | |
| 604 '(string,\n' | |
| 605 'bytes, integer, floating point number, complex number) with ' | |
| 606 'the given\n' | |
| 607 'value. The value may be approximated in the case of ' | |
| 608 'floating point\n' | |
| 609 'and imaginary (complex) literals. See section Literals for ' | |
| 610 'details.\n' | |
| 611 '\n' | |
| 612 'All literals correspond to immutable data types, and hence ' | |
| 613 'the\n' | |
| 614 'object’s identity is less important than its value. ' | |
| 615 'Multiple\n' | |
| 616 'evaluations of literals with the same value (either the ' | |
| 617 'same\n' | |
| 618 'occurrence in the program text or a different occurrence) ' | |
| 619 'may obtain\n' | |
| 620 'the same object or a different object with the same ' | |
| 621 'value.\n', | |
| 622 'attribute-access': 'Customizing attribute access\n' | |
| 623 '****************************\n' | |
| 624 '\n' | |
| 625 'The following methods can be defined to customize the ' | |
| 626 'meaning of\n' | |
| 627 'attribute access (use of, assignment to, or deletion of ' | |
| 628 '"x.name") for\n' | |
| 629 'class instances.\n' | |
| 630 '\n' | |
| 631 'object.__getattr__(self, name)\n' | |
| 632 '\n' | |
| 633 ' Called when the default attribute access fails with ' | |
| 634 'an\n' | |
| 635 ' "AttributeError" (either "__getattribute__()" raises ' | |
| 636 'an\n' | |
| 637 ' "AttributeError" because *name* is not an instance ' | |
| 638 'attribute or an\n' | |
| 639 ' attribute in the class tree for "self"; or ' | |
| 640 '"__get__()" of a *name*\n' | |
| 641 ' property raises "AttributeError"). This method ' | |
| 642 'should either\n' | |
| 643 ' return the (computed) attribute value or raise an ' | |
| 644 '"AttributeError"\n' | |
| 645 ' exception.\n' | |
| 646 '\n' | |
| 647 ' Note that if the attribute is found through the ' | |
| 648 'normal mechanism,\n' | |
| 649 ' "__getattr__()" is not called. (This is an ' | |
| 650 'intentional asymmetry\n' | |
| 651 ' between "__getattr__()" and "__setattr__()".) This is ' | |
| 652 'done both for\n' | |
| 653 ' efficiency reasons and because otherwise ' | |
| 654 '"__getattr__()" would have\n' | |
| 655 ' no way to access other attributes of the instance. ' | |
| 656 'Note that at\n' | |
| 657 ' least for instance variables, you can fake total ' | |
| 658 'control by not\n' | |
| 659 ' inserting any values in the instance attribute ' | |
| 660 'dictionary (but\n' | |
| 661 ' instead inserting them in another object). See the\n' | |
| 662 ' "__getattribute__()" method below for a way to ' | |
| 663 'actually get total\n' | |
| 664 ' control over attribute access.\n' | |
| 665 '\n' | |
| 666 'object.__getattribute__(self, name)\n' | |
| 667 '\n' | |
| 668 ' Called unconditionally to implement attribute ' | |
| 669 'accesses for\n' | |
| 670 ' instances of the class. If the class also defines ' | |
| 671 '"__getattr__()",\n' | |
| 672 ' the latter will not be called unless ' | |
| 673 '"__getattribute__()" either\n' | |
| 674 ' calls it explicitly or raises an "AttributeError". ' | |
| 675 'This method\n' | |
| 676 ' should return the (computed) attribute value or raise ' | |
| 677 'an\n' | |
| 678 ' "AttributeError" exception. In order to avoid ' | |
| 679 'infinite recursion in\n' | |
| 680 ' this method, its implementation should always call ' | |
| 681 'the base class\n' | |
| 682 ' method with the same name to access any attributes it ' | |
| 683 'needs, for\n' | |
| 684 ' example, "object.__getattribute__(self, name)".\n' | |
| 685 '\n' | |
| 686 ' Note: This method may still be bypassed when looking ' | |
| 687 'up special\n' | |
| 688 ' methods as the result of implicit invocation via ' | |
| 689 'language syntax\n' | |
| 690 ' or built-in functions. See Special method lookup.\n' | |
| 691 '\n' | |
| 692 'object.__setattr__(self, name, value)\n' | |
| 693 '\n' | |
| 694 ' Called when an attribute assignment is attempted. ' | |
| 695 'This is called\n' | |
| 696 ' instead of the normal mechanism (i.e. store the value ' | |
| 697 'in the\n' | |
| 698 ' instance dictionary). *name* is the attribute name, ' | |
| 699 '*value* is the\n' | |
| 700 ' value to be assigned to it.\n' | |
| 701 '\n' | |
| 702 ' If "__setattr__()" wants to assign to an instance ' | |
| 703 'attribute, it\n' | |
| 704 ' should call the base class method with the same name, ' | |
| 705 'for example,\n' | |
| 706 ' "object.__setattr__(self, name, value)".\n' | |
| 707 '\n' | |
| 708 'object.__delattr__(self, name)\n' | |
| 709 '\n' | |
| 710 ' Like "__setattr__()" but for attribute deletion ' | |
| 711 'instead of\n' | |
| 712 ' assignment. This should only be implemented if "del ' | |
| 713 'obj.name" is\n' | |
| 714 ' meaningful for the object.\n' | |
| 715 '\n' | |
| 716 'object.__dir__(self)\n' | |
| 717 '\n' | |
| 718 ' Called when "dir()" is called on the object. A ' | |
| 719 'sequence must be\n' | |
| 720 ' returned. "dir()" converts the returned sequence to a ' | |
| 721 'list and\n' | |
| 722 ' sorts it.\n' | |
| 723 '\n' | |
| 724 '\n' | |
| 725 'Customizing module attribute access\n' | |
| 726 '===================================\n' | |
| 727 '\n' | |
| 728 'Special names "__getattr__" and "__dir__" can be also ' | |
| 729 'used to\n' | |
| 730 'customize access to module attributes. The "__getattr__" ' | |
| 731 'function at\n' | |
| 732 'the module level should accept one argument which is the ' | |
| 733 'name of an\n' | |
| 734 'attribute and return the computed value or raise an ' | |
| 735 '"AttributeError".\n' | |
| 736 'If an attribute is not found on a module object through ' | |
| 737 'the normal\n' | |
| 738 'lookup, i.e. "object.__getattribute__()", then ' | |
| 739 '"__getattr__" is\n' | |
| 740 'searched in the module "__dict__" before raising an ' | |
| 741 '"AttributeError".\n' | |
| 742 'If found, it is called with the attribute name and the ' | |
| 743 'result is\n' | |
| 744 'returned.\n' | |
| 745 '\n' | |
| 746 'The "__dir__" function should accept no arguments, and ' | |
| 747 'return a\n' | |
| 748 'sequence of strings that represents the names accessible ' | |
| 749 'on module. If\n' | |
| 750 'present, this function overrides the standard "dir()" ' | |
| 751 'search on a\n' | |
| 752 'module.\n' | |
| 753 '\n' | |
| 754 'For a more fine grained customization of the module ' | |
| 755 'behavior (setting\n' | |
| 756 'attributes, properties, etc.), one can set the ' | |
| 757 '"__class__" attribute\n' | |
| 758 'of a module object to a subclass of "types.ModuleType". ' | |
| 759 'For example:\n' | |
| 760 '\n' | |
| 761 ' import sys\n' | |
| 762 ' from types import ModuleType\n' | |
| 763 '\n' | |
| 764 ' class VerboseModule(ModuleType):\n' | |
| 765 ' def __repr__(self):\n' | |
| 766 " return f'Verbose {self.__name__}'\n" | |
| 767 '\n' | |
| 768 ' def __setattr__(self, attr, value):\n' | |
| 769 " print(f'Setting {attr}...')\n" | |
| 770 ' super().__setattr__(attr, value)\n' | |
| 771 '\n' | |
| 772 ' sys.modules[__name__].__class__ = VerboseModule\n' | |
| 773 '\n' | |
| 774 'Note: Defining module "__getattr__" and setting module ' | |
| 775 '"__class__"\n' | |
| 776 ' only affect lookups made using the attribute access ' | |
| 777 'syntax –\n' | |
| 778 ' directly accessing the module globals (whether by code ' | |
| 779 'within the\n' | |
| 780 ' module, or via a reference to the module’s globals ' | |
| 781 'dictionary) is\n' | |
| 782 ' unaffected.\n' | |
| 783 '\n' | |
| 784 'Changed in version 3.5: "__class__" module attribute is ' | |
| 785 'now writable.\n' | |
| 786 '\n' | |
| 787 'New in version 3.7: "__getattr__" and "__dir__" module ' | |
| 788 'attributes.\n' | |
| 789 '\n' | |
| 790 'See also:\n' | |
| 791 '\n' | |
| 792 ' **PEP 562** - Module __getattr__ and __dir__\n' | |
| 793 ' Describes the "__getattr__" and "__dir__" functions ' | |
| 794 'on modules.\n' | |
| 795 '\n' | |
| 796 '\n' | |
| 797 'Implementing Descriptors\n' | |
| 798 '========================\n' | |
| 799 '\n' | |
| 800 'The following methods only apply when an instance of the ' | |
| 801 'class\n' | |
| 802 'containing the method (a so-called *descriptor* class) ' | |
| 803 'appears in an\n' | |
| 804 '*owner* class (the descriptor must be in either the ' | |
| 805 'owner’s class\n' | |
| 806 'dictionary or in the class dictionary for one of its ' | |
| 807 'parents). In the\n' | |
| 808 'examples below, “the attribute” refers to the attribute ' | |
| 809 'whose name is\n' | |
| 810 'the key of the property in the owner class’ "__dict__".\n' | |
| 811 '\n' | |
| 812 'object.__get__(self, instance, owner=None)\n' | |
| 813 '\n' | |
| 814 ' Called to get the attribute of the owner class (class ' | |
| 815 'attribute\n' | |
| 816 ' access) or of an instance of that class (instance ' | |
| 817 'attribute\n' | |
| 818 ' access). The optional *owner* argument is the owner ' | |
| 819 'class, while\n' | |
| 820 ' *instance* is the instance that the attribute was ' | |
| 821 'accessed through,\n' | |
| 822 ' or "None" when the attribute is accessed through the ' | |
| 823 '*owner*.\n' | |
| 824 '\n' | |
| 825 ' This method should return the computed attribute ' | |
| 826 'value or raise an\n' | |
| 827 ' "AttributeError" exception.\n' | |
| 828 '\n' | |
| 829 ' **PEP 252** specifies that "__get__()" is callable ' | |
| 830 'with one or two\n' | |
| 831 ' arguments. Python’s own built-in descriptors support ' | |
| 832 'this\n' | |
| 833 ' specification; however, it is likely that some ' | |
| 834 'third-party tools\n' | |
| 835 ' have descriptors that require both arguments. ' | |
| 836 'Python’s own\n' | |
| 837 ' "__getattribute__()" implementation always passes in ' | |
| 838 'both arguments\n' | |
| 839 ' whether they are required or not.\n' | |
| 840 '\n' | |
| 841 'object.__set__(self, instance, value)\n' | |
| 842 '\n' | |
| 843 ' Called to set the attribute on an instance *instance* ' | |
| 844 'of the owner\n' | |
| 845 ' class to a new value, *value*.\n' | |
| 846 '\n' | |
| 847 ' Note, adding "__set__()" or "__delete__()" changes ' | |
| 848 'the kind of\n' | |
| 849 ' descriptor to a “data descriptor”. See Invoking ' | |
| 850 'Descriptors for\n' | |
| 851 ' more details.\n' | |
| 852 '\n' | |
| 853 'object.__delete__(self, instance)\n' | |
| 854 '\n' | |
| 855 ' Called to delete the attribute on an instance ' | |
| 856 '*instance* of the\n' | |
| 857 ' owner class.\n' | |
| 858 '\n' | |
| 859 'object.__set_name__(self, owner, name)\n' | |
| 860 '\n' | |
| 861 ' Called at the time the owning class *owner* is ' | |
| 862 'created. The\n' | |
| 863 ' descriptor has been assigned to *name*.\n' | |
| 864 '\n' | |
| 865 ' Note: "__set_name__()" is only called implicitly as ' | |
| 866 'part of the\n' | |
| 867 ' "type" constructor, so it will need to be called ' | |
| 868 'explicitly with\n' | |
| 869 ' the appropriate parameters when a descriptor is ' | |
| 870 'added to a class\n' | |
| 871 ' after initial creation:\n' | |
| 872 '\n' | |
| 873 ' class A:\n' | |
| 874 ' pass\n' | |
| 875 ' descr = custom_descriptor()\n' | |
| 876 ' A.attr = descr\n' | |
| 877 " descr.__set_name__(A, 'attr')\n" | |
| 878 '\n' | |
| 879 ' See Creating the class object for more details.\n' | |
| 880 '\n' | |
| 881 ' New in version 3.6.\n' | |
| 882 '\n' | |
| 883 'The attribute "__objclass__" is interpreted by the ' | |
| 884 '"inspect" module as\n' | |
| 885 'specifying the class where this object was defined ' | |
| 886 '(setting this\n' | |
| 887 'appropriately can assist in runtime introspection of ' | |
| 888 'dynamic class\n' | |
| 889 'attributes). For callables, it may indicate that an ' | |
| 890 'instance of the\n' | |
| 891 'given type (or a subclass) is expected or required as ' | |
| 892 'the first\n' | |
| 893 'positional argument (for example, CPython sets this ' | |
| 894 'attribute for\n' | |
| 895 'unbound methods that are implemented in C).\n' | |
| 896 '\n' | |
| 897 '\n' | |
| 898 'Invoking Descriptors\n' | |
| 899 '====================\n' | |
| 900 '\n' | |
| 901 'In general, a descriptor is an object attribute with ' | |
| 902 '“binding\n' | |
| 903 'behavior”, one whose attribute access has been ' | |
| 904 'overridden by methods\n' | |
| 905 'in the descriptor protocol: "__get__()", "__set__()", ' | |
| 906 'and\n' | |
| 907 '"__delete__()". If any of those methods are defined for ' | |
| 908 'an object, it\n' | |
| 909 'is said to be a descriptor.\n' | |
| 910 '\n' | |
| 911 'The default behavior for attribute access is to get, ' | |
| 912 'set, or delete\n' | |
| 913 'the attribute from an object’s dictionary. For instance, ' | |
| 914 '"a.x" has a\n' | |
| 915 'lookup chain starting with "a.__dict__[\'x\']", then\n' | |
| 916 '"type(a).__dict__[\'x\']", and continuing through the ' | |
| 917 'base classes of\n' | |
| 918 '"type(a)" excluding metaclasses.\n' | |
| 919 '\n' | |
| 920 'However, if the looked-up value is an object defining ' | |
| 921 'one of the\n' | |
| 922 'descriptor methods, then Python may override the default ' | |
| 923 'behavior and\n' | |
| 924 'invoke the descriptor method instead. Where this occurs ' | |
| 925 'in the\n' | |
| 926 'precedence chain depends on which descriptor methods ' | |
| 927 'were defined and\n' | |
| 928 'how they were called.\n' | |
| 929 '\n' | |
| 930 'The starting point for descriptor invocation is a ' | |
| 931 'binding, "a.x". How\n' | |
| 932 'the arguments are assembled depends on "a":\n' | |
| 933 '\n' | |
| 934 'Direct Call\n' | |
| 935 ' The simplest and least common call is when user code ' | |
| 936 'directly\n' | |
| 937 ' invokes a descriptor method: "x.__get__(a)".\n' | |
| 938 '\n' | |
| 939 'Instance Binding\n' | |
| 940 ' If binding to an object instance, "a.x" is ' | |
| 941 'transformed into the\n' | |
| 942 ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' | |
| 943 '\n' | |
| 944 'Class Binding\n' | |
| 945 ' If binding to a class, "A.x" is transformed into the ' | |
| 946 'call:\n' | |
| 947 ' "A.__dict__[\'x\'].__get__(None, A)".\n' | |
| 948 '\n' | |
| 949 'Super Binding\n' | |
| 950 ' If "a" is an instance of "super", then the binding ' | |
| 951 '"super(B,\n' | |
| 952 ' obj).m()" searches "obj.__class__.__mro__" for the ' | |
| 953 'base class "A"\n' | |
| 954 ' immediately preceding "B" and then invokes the ' | |
| 955 'descriptor with the\n' | |
| 956 ' call: "A.__dict__[\'m\'].__get__(obj, ' | |
| 957 'obj.__class__)".\n' | |
| 958 '\n' | |
| 959 'For instance bindings, the precedence of descriptor ' | |
| 960 'invocation depends\n' | |
| 961 'on the which descriptor methods are defined. A ' | |
| 962 'descriptor can define\n' | |
| 963 'any combination of "__get__()", "__set__()" and ' | |
| 964 '"__delete__()". If it\n' | |
| 965 'does not define "__get__()", then accessing the ' | |
| 966 'attribute will return\n' | |
| 967 'the descriptor object itself unless there is a value in ' | |
| 968 'the object’s\n' | |
| 969 'instance dictionary. If the descriptor defines ' | |
| 970 '"__set__()" and/or\n' | |
| 971 '"__delete__()", it is a data descriptor; if it defines ' | |
| 972 'neither, it is\n' | |
| 973 'a non-data descriptor. Normally, data descriptors ' | |
| 974 'define both\n' | |
| 975 '"__get__()" and "__set__()", while non-data descriptors ' | |
| 976 'have just the\n' | |
| 977 '"__get__()" method. Data descriptors with "__set__()" ' | |
| 978 'and "__get__()"\n' | |
| 979 'defined always override a redefinition in an instance ' | |
| 980 'dictionary. In\n' | |
| 981 'contrast, non-data descriptors can be overridden by ' | |
| 982 'instances.\n' | |
| 983 '\n' | |
| 984 'Python methods (including "staticmethod()" and ' | |
| 985 '"classmethod()") are\n' | |
| 986 'implemented as non-data descriptors. Accordingly, ' | |
| 987 'instances can\n' | |
| 988 'redefine and override methods. This allows individual ' | |
| 989 'instances to\n' | |
| 990 'acquire behaviors that differ from other instances of ' | |
| 991 'the same class.\n' | |
| 992 '\n' | |
| 993 'The "property()" function is implemented as a data ' | |
| 994 'descriptor.\n' | |
| 995 'Accordingly, instances cannot override the behavior of a ' | |
| 996 'property.\n' | |
| 997 '\n' | |
| 998 '\n' | |
| 999 '__slots__\n' | |
| 1000 '=========\n' | |
| 1001 '\n' | |
| 1002 '*__slots__* allow us to explicitly declare data members ' | |
| 1003 '(like\n' | |
| 1004 'properties) and deny the creation of *__dict__* and ' | |
| 1005 '*__weakref__*\n' | |
| 1006 '(unless explicitly declared in *__slots__* or available ' | |
| 1007 'in a parent.)\n' | |
| 1008 '\n' | |
| 1009 'The space saved over using *__dict__* can be ' | |
| 1010 'significant. Attribute\n' | |
| 1011 'lookup speed can be significantly improved as well.\n' | |
| 1012 '\n' | |
| 1013 'object.__slots__\n' | |
| 1014 '\n' | |
| 1015 ' This class variable can be assigned a string, ' | |
| 1016 'iterable, or sequence\n' | |
| 1017 ' of strings with variable names used by instances. ' | |
| 1018 '*__slots__*\n' | |
| 1019 ' reserves space for the declared variables and ' | |
| 1020 'prevents the\n' | |
| 1021 ' automatic creation of *__dict__* and *__weakref__* ' | |
| 1022 'for each\n' | |
| 1023 ' instance.\n' | |
| 1024 '\n' | |
| 1025 '\n' | |
| 1026 'Notes on using *__slots__*\n' | |
| 1027 '--------------------------\n' | |
| 1028 '\n' | |
| 1029 '* When inheriting from a class without *__slots__*, the ' | |
| 1030 '*__dict__*\n' | |
| 1031 ' and *__weakref__* attribute of the instances will ' | |
| 1032 'always be\n' | |
| 1033 ' accessible.\n' | |
| 1034 '\n' | |
| 1035 '* Without a *__dict__* variable, instances cannot be ' | |
| 1036 'assigned new\n' | |
| 1037 ' variables not listed in the *__slots__* definition. ' | |
| 1038 'Attempts to\n' | |
| 1039 ' assign to an unlisted variable name raises ' | |
| 1040 '"AttributeError". If\n' | |
| 1041 ' dynamic assignment of new variables is desired, then ' | |
| 1042 'add\n' | |
| 1043 ' "\'__dict__\'" to the sequence of strings in the ' | |
| 1044 '*__slots__*\n' | |
| 1045 ' declaration.\n' | |
| 1046 '\n' | |
| 1047 '* Without a *__weakref__* variable for each instance, ' | |
| 1048 'classes\n' | |
| 1049 ' defining *__slots__* do not support weak references to ' | |
| 1050 'its\n' | |
| 1051 ' instances. If weak reference support is needed, then ' | |
| 1052 'add\n' | |
| 1053 ' "\'__weakref__\'" to the sequence of strings in the ' | |
| 1054 '*__slots__*\n' | |
| 1055 ' declaration.\n' | |
| 1056 '\n' | |
| 1057 '* *__slots__* are implemented at the class level by ' | |
| 1058 'creating\n' | |
| 1059 ' descriptors (Implementing Descriptors) for each ' | |
| 1060 'variable name. As a\n' | |
| 1061 ' result, class attributes cannot be used to set default ' | |
| 1062 'values for\n' | |
| 1063 ' instance variables defined by *__slots__*; otherwise, ' | |
| 1064 'the class\n' | |
| 1065 ' attribute would overwrite the descriptor assignment.\n' | |
| 1066 '\n' | |
| 1067 '* The action of a *__slots__* declaration is not limited ' | |
| 1068 'to the\n' | |
| 1069 ' class where it is defined. *__slots__* declared in ' | |
| 1070 'parents are\n' | |
| 1071 ' available in child classes. However, child subclasses ' | |
| 1072 'will get a\n' | |
| 1073 ' *__dict__* and *__weakref__* unless they also define ' | |
| 1074 '*__slots__*\n' | |
| 1075 ' (which should only contain names of any *additional* ' | |
| 1076 'slots).\n' | |
| 1077 '\n' | |
| 1078 '* If a class defines a slot also defined in a base ' | |
| 1079 'class, the\n' | |
| 1080 ' instance variable defined by the base class slot is ' | |
| 1081 'inaccessible\n' | |
| 1082 ' (except by retrieving its descriptor directly from the ' | |
| 1083 'base class).\n' | |
| 1084 ' This renders the meaning of the program undefined. In ' | |
| 1085 'the future, a\n' | |
| 1086 ' check may be added to prevent this.\n' | |
| 1087 '\n' | |
| 1088 '* Nonempty *__slots__* does not work for classes derived ' | |
| 1089 'from\n' | |
| 1090 ' “variable-length” built-in types such as "int", ' | |
| 1091 '"bytes" and "tuple".\n' | |
| 1092 '\n' | |
| 1093 '* Any non-string iterable may be assigned to ' | |
| 1094 '*__slots__*. Mappings\n' | |
| 1095 ' may also be used; however, in the future, special ' | |
| 1096 'meaning may be\n' | |
| 1097 ' assigned to the values corresponding to each key.\n' | |
| 1098 '\n' | |
| 1099 '* *__class__* assignment works only if both classes have ' | |
| 1100 'the same\n' | |
| 1101 ' *__slots__*.\n' | |
| 1102 '\n' | |
| 1103 '* Multiple inheritance with multiple slotted parent ' | |
| 1104 'classes can be\n' | |
| 1105 ' used, but only one parent is allowed to have ' | |
| 1106 'attributes created by\n' | |
| 1107 ' slots (the other bases must have empty slot layouts) - ' | |
| 1108 'violations\n' | |
| 1109 ' raise "TypeError".\n' | |
| 1110 '\n' | |
| 1111 '* If an iterator is used for *__slots__* then a ' | |
| 1112 'descriptor is\n' | |
| 1113 ' created for each of the iterator’s values. However, ' | |
| 1114 'the *__slots__*\n' | |
| 1115 ' attribute will be an empty iterator.\n', | |
| 1116 'attribute-references': 'Attribute references\n' | |
| 1117 '********************\n' | |
| 1118 '\n' | |
| 1119 'An attribute reference is a primary followed by a ' | |
| 1120 'period and a name:\n' | |
| 1121 '\n' | |
| 1122 ' attributeref ::= primary "." identifier\n' | |
| 1123 '\n' | |
| 1124 'The primary must evaluate to an object of a type ' | |
| 1125 'that supports\n' | |
| 1126 'attribute references, which most objects do. This ' | |
| 1127 'object is then\n' | |
| 1128 'asked to produce the attribute whose name is the ' | |
| 1129 'identifier. This\n' | |
| 1130 'production can be customized by overriding the ' | |
| 1131 '"__getattr__()" method.\n' | |
| 1132 'If this attribute is not available, the exception ' | |
| 1133 '"AttributeError" is\n' | |
| 1134 'raised. Otherwise, the type and value of the object ' | |
| 1135 'produced is\n' | |
| 1136 'determined by the object. Multiple evaluations of ' | |
| 1137 'the same attribute\n' | |
| 1138 'reference may yield different objects.\n', | |
| 1139 'augassign': 'Augmented assignment statements\n' | |
| 1140 '*******************************\n' | |
| 1141 '\n' | |
| 1142 'Augmented assignment is the combination, in a single statement, ' | |
| 1143 'of a\n' | |
| 1144 'binary operation and an assignment statement:\n' | |
| 1145 '\n' | |
| 1146 ' augmented_assignment_stmt ::= augtarget augop ' | |
| 1147 '(expression_list | yield_expression)\n' | |
| 1148 ' augtarget ::= identifier | attributeref | ' | |
| 1149 'subscription | slicing\n' | |
| 1150 ' augop ::= "+=" | "-=" | "*=" | "@=" | ' | |
| 1151 '"/=" | "//=" | "%=" | "**="\n' | |
| 1152 ' | ">>=" | "<<=" | "&=" | "^=" | "|="\n' | |
| 1153 '\n' | |
| 1154 '(See section Primaries for the syntax definitions of the last ' | |
| 1155 'three\n' | |
| 1156 'symbols.)\n' | |
| 1157 '\n' | |
| 1158 'An augmented assignment evaluates the target (which, unlike ' | |
| 1159 'normal\n' | |
| 1160 'assignment statements, cannot be an unpacking) and the ' | |
| 1161 'expression\n' | |
| 1162 'list, performs the binary operation specific to the type of ' | |
| 1163 'assignment\n' | |
| 1164 'on the two operands, and assigns the result to the original ' | |
| 1165 'target.\n' | |
| 1166 'The target is only evaluated once.\n' | |
| 1167 '\n' | |
| 1168 'An augmented assignment expression like "x += 1" can be ' | |
| 1169 'rewritten as\n' | |
| 1170 '"x = x + 1" to achieve a similar, but not exactly equal effect. ' | |
| 1171 'In the\n' | |
| 1172 'augmented version, "x" is only evaluated once. Also, when ' | |
| 1173 'possible,\n' | |
| 1174 'the actual operation is performed *in-place*, meaning that ' | |
| 1175 'rather than\n' | |
| 1176 'creating a new object and assigning that to the target, the old ' | |
| 1177 'object\n' | |
| 1178 'is modified instead.\n' | |
| 1179 '\n' | |
| 1180 'Unlike normal assignments, augmented assignments evaluate the ' | |
| 1181 'left-\n' | |
| 1182 'hand side *before* evaluating the right-hand side. For ' | |
| 1183 'example, "a[i]\n' | |
| 1184 '+= f(x)" first looks-up "a[i]", then it evaluates "f(x)" and ' | |
| 1185 'performs\n' | |
| 1186 'the addition, and lastly, it writes the result back to "a[i]".\n' | |
| 1187 '\n' | |
| 1188 'With the exception of assigning to tuples and multiple targets ' | |
| 1189 'in a\n' | |
| 1190 'single statement, the assignment done by augmented assignment\n' | |
| 1191 'statements is handled the same way as normal assignments. ' | |
| 1192 'Similarly,\n' | |
| 1193 'with the exception of the possible *in-place* behavior, the ' | |
| 1194 'binary\n' | |
| 1195 'operation performed by augmented assignment is the same as the ' | |
| 1196 'normal\n' | |
| 1197 'binary operations.\n' | |
| 1198 '\n' | |
| 1199 'For targets which are attribute references, the same caveat ' | |
| 1200 'about\n' | |
| 1201 'class and instance attributes applies as for regular ' | |
| 1202 'assignments.\n', | |
| 1203 'await': 'Await expression\n' | |
| 1204 '****************\n' | |
| 1205 '\n' | |
| 1206 'Suspend the execution of *coroutine* on an *awaitable* object. Can\n' | |
| 1207 'only be used inside a *coroutine function*.\n' | |
| 1208 '\n' | |
| 1209 ' await_expr ::= "await" primary\n' | |
| 1210 '\n' | |
| 1211 'New in version 3.5.\n', | |
| 1212 'binary': 'Binary arithmetic operations\n' | |
| 1213 '****************************\n' | |
| 1214 '\n' | |
| 1215 'The binary arithmetic operations have the conventional priority\n' | |
| 1216 'levels. Note that some of these operations also apply to certain ' | |
| 1217 'non-\n' | |
| 1218 'numeric types. Apart from the power operator, there are only two\n' | |
| 1219 'levels, one for multiplicative operators and one for additive\n' | |
| 1220 'operators:\n' | |
| 1221 '\n' | |
| 1222 ' m_expr ::= u_expr | m_expr "*" u_expr | m_expr "@" m_expr |\n' | |
| 1223 ' m_expr "//" u_expr | m_expr "/" u_expr |\n' | |
| 1224 ' m_expr "%" u_expr\n' | |
| 1225 ' a_expr ::= m_expr | a_expr "+" m_expr | a_expr "-" m_expr\n' | |
| 1226 '\n' | |
| 1227 'The "*" (multiplication) operator yields the product of its ' | |
| 1228 'arguments.\n' | |
| 1229 'The arguments must either both be numbers, or one argument must be ' | |
| 1230 'an\n' | |
| 1231 'integer and the other must be a sequence. In the former case, the\n' | |
| 1232 'numbers are converted to a common type and then multiplied ' | |
| 1233 'together.\n' | |
| 1234 'In the latter case, sequence repetition is performed; a negative\n' | |
| 1235 'repetition factor yields an empty sequence.\n' | |
| 1236 '\n' | |
| 1237 'The "@" (at) operator is intended to be used for matrix\n' | |
| 1238 'multiplication. No builtin Python types implement this operator.\n' | |
| 1239 '\n' | |
| 1240 'New in version 3.5.\n' | |
| 1241 '\n' | |
| 1242 'The "/" (division) and "//" (floor division) operators yield the\n' | |
| 1243 'quotient of their arguments. The numeric arguments are first\n' | |
| 1244 'converted to a common type. Division of integers yields a float, ' | |
| 1245 'while\n' | |
| 1246 'floor division of integers results in an integer; the result is ' | |
| 1247 'that\n' | |
| 1248 'of mathematical division with the ‘floor’ function applied to the\n' | |
| 1249 'result. Division by zero raises the "ZeroDivisionError" ' | |
| 1250 'exception.\n' | |
| 1251 '\n' | |
| 1252 'The "%" (modulo) operator yields the remainder from the division ' | |
| 1253 'of\n' | |
| 1254 'the first argument by the second. The numeric arguments are ' | |
| 1255 'first\n' | |
| 1256 'converted to a common type. A zero right argument raises the\n' | |
| 1257 '"ZeroDivisionError" exception. The arguments may be floating ' | |
| 1258 'point\n' | |
| 1259 'numbers, e.g., "3.14%0.7" equals "0.34" (since "3.14" equals ' | |
| 1260 '"4*0.7 +\n' | |
| 1261 '0.34".) The modulo operator always yields a result with the same ' | |
| 1262 'sign\n' | |
| 1263 'as its second operand (or zero); the absolute value of the result ' | |
| 1264 'is\n' | |
| 1265 'strictly smaller than the absolute value of the second operand ' | |
| 1266 '[1].\n' | |
| 1267 '\n' | |
| 1268 'The floor division and modulo operators are connected by the ' | |
| 1269 'following\n' | |
| 1270 'identity: "x == (x//y)*y + (x%y)". Floor division and modulo are ' | |
| 1271 'also\n' | |
| 1272 'connected with the built-in function "divmod()": "divmod(x, y) ==\n' | |
| 1273 '(x//y, x%y)". [2].\n' | |
| 1274 '\n' | |
| 1275 'In addition to performing the modulo operation on numbers, the ' | |
| 1276 '"%"\n' | |
| 1277 'operator is also overloaded by string objects to perform ' | |
| 1278 'old-style\n' | |
| 1279 'string formatting (also known as interpolation). The syntax for\n' | |
| 1280 'string formatting is described in the Python Library Reference,\n' | |
| 1281 'section printf-style String Formatting.\n' | |
| 1282 '\n' | |
| 1283 'The floor division operator, the modulo operator, and the ' | |
| 1284 '"divmod()"\n' | |
| 1285 'function are not defined for complex numbers. Instead, convert to ' | |
| 1286 'a\n' | |
| 1287 'floating point number using the "abs()" function if appropriate.\n' | |
| 1288 '\n' | |
| 1289 'The "+" (addition) operator yields the sum of its arguments. The\n' | |
| 1290 'arguments must either both be numbers or both be sequences of the ' | |
| 1291 'same\n' | |
| 1292 'type. In the former case, the numbers are converted to a common ' | |
| 1293 'type\n' | |
| 1294 'and then added together. In the latter case, the sequences are\n' | |
| 1295 'concatenated.\n' | |
| 1296 '\n' | |
| 1297 'The "-" (subtraction) operator yields the difference of its ' | |
| 1298 'arguments.\n' | |
| 1299 'The numeric arguments are first converted to a common type.\n', | |
| 1300 'bitwise': 'Binary bitwise operations\n' | |
| 1301 '*************************\n' | |
| 1302 '\n' | |
| 1303 'Each of the three bitwise operations has a different priority ' | |
| 1304 'level:\n' | |
| 1305 '\n' | |
| 1306 ' and_expr ::= shift_expr | and_expr "&" shift_expr\n' | |
| 1307 ' xor_expr ::= and_expr | xor_expr "^" and_expr\n' | |
| 1308 ' or_expr ::= xor_expr | or_expr "|" xor_expr\n' | |
| 1309 '\n' | |
| 1310 'The "&" operator yields the bitwise AND of its arguments, which ' | |
| 1311 'must\n' | |
| 1312 'be integers.\n' | |
| 1313 '\n' | |
| 1314 'The "^" operator yields the bitwise XOR (exclusive OR) of its\n' | |
| 1315 'arguments, which must be integers.\n' | |
| 1316 '\n' | |
| 1317 'The "|" operator yields the bitwise (inclusive) OR of its ' | |
| 1318 'arguments,\n' | |
| 1319 'which must be integers.\n', | |
| 1320 'bltin-code-objects': 'Code Objects\n' | |
| 1321 '************\n' | |
| 1322 '\n' | |
| 1323 'Code objects are used by the implementation to ' | |
| 1324 'represent “pseudo-\n' | |
| 1325 'compiled” executable Python code such as a function ' | |
| 1326 'body. They differ\n' | |
| 1327 'from function objects because they don’t contain a ' | |
| 1328 'reference to their\n' | |
| 1329 'global execution environment. Code objects are ' | |
| 1330 'returned by the built-\n' | |
| 1331 'in "compile()" function and can be extracted from ' | |
| 1332 'function objects\n' | |
| 1333 'through their "__code__" attribute. See also the ' | |
| 1334 '"code" module.\n' | |
| 1335 '\n' | |
| 1336 'A code object can be executed or evaluated by passing ' | |
| 1337 'it (instead of a\n' | |
| 1338 'source string) to the "exec()" or "eval()" built-in ' | |
| 1339 'functions.\n' | |
| 1340 '\n' | |
| 1341 'See The standard type hierarchy for more ' | |
| 1342 'information.\n', | |
| 1343 'bltin-ellipsis-object': 'The Ellipsis Object\n' | |
| 1344 '*******************\n' | |
| 1345 '\n' | |
| 1346 'This object is commonly used by slicing (see ' | |
| 1347 'Slicings). It supports\n' | |
| 1348 'no special operations. There is exactly one ' | |
| 1349 'ellipsis object, named\n' | |
| 1350 '"Ellipsis" (a built-in name). "type(Ellipsis)()" ' | |
| 1351 'produces the\n' | |
| 1352 '"Ellipsis" singleton.\n' | |
| 1353 '\n' | |
| 1354 'It is written as "Ellipsis" or "...".\n', | |
| 1355 'bltin-null-object': 'The Null Object\n' | |
| 1356 '***************\n' | |
| 1357 '\n' | |
| 1358 'This object is returned by functions that don’t ' | |
| 1359 'explicitly return a\n' | |
| 1360 'value. It supports no special operations. There is ' | |
| 1361 'exactly one null\n' | |
| 1362 'object, named "None" (a built-in name). "type(None)()" ' | |
| 1363 'produces the\n' | |
| 1364 'same singleton.\n' | |
| 1365 '\n' | |
| 1366 'It is written as "None".\n', | |
| 1367 'bltin-type-objects': 'Type Objects\n' | |
| 1368 '************\n' | |
| 1369 '\n' | |
| 1370 'Type objects represent the various object types. An ' | |
| 1371 'object’s type is\n' | |
| 1372 'accessed by the built-in function "type()". There are ' | |
| 1373 'no special\n' | |
| 1374 'operations on types. The standard module "types" ' | |
| 1375 'defines names for\n' | |
| 1376 'all standard built-in types.\n' | |
| 1377 '\n' | |
| 1378 'Types are written like this: "<class \'int\'>".\n', | |
| 1379 'booleans': 'Boolean operations\n' | |
| 1380 '******************\n' | |
| 1381 '\n' | |
| 1382 ' or_test ::= and_test | or_test "or" and_test\n' | |
| 1383 ' and_test ::= not_test | and_test "and" not_test\n' | |
| 1384 ' not_test ::= comparison | "not" not_test\n' | |
| 1385 '\n' | |
| 1386 'In the context of Boolean operations, and also when expressions ' | |
| 1387 'are\n' | |
| 1388 'used by control flow statements, the following values are ' | |
| 1389 'interpreted\n' | |
| 1390 'as false: "False", "None", numeric zero of all types, and empty\n' | |
| 1391 'strings and containers (including strings, tuples, lists,\n' | |
| 1392 'dictionaries, sets and frozensets). All other values are ' | |
| 1393 'interpreted\n' | |
| 1394 'as true. User-defined objects can customize their truth value ' | |
| 1395 'by\n' | |
| 1396 'providing a "__bool__()" method.\n' | |
| 1397 '\n' | |
| 1398 'The operator "not" yields "True" if its argument is false, ' | |
| 1399 '"False"\n' | |
| 1400 'otherwise.\n' | |
| 1401 '\n' | |
| 1402 'The expression "x and y" first evaluates *x*; if *x* is false, ' | |
| 1403 'its\n' | |
| 1404 'value is returned; otherwise, *y* is evaluated and the resulting ' | |
| 1405 'value\n' | |
| 1406 'is returned.\n' | |
| 1407 '\n' | |
| 1408 'The expression "x or y" first evaluates *x*; if *x* is true, its ' | |
| 1409 'value\n' | |
| 1410 'is returned; otherwise, *y* is evaluated and the resulting value ' | |
| 1411 'is\n' | |
| 1412 'returned.\n' | |
| 1413 '\n' | |
| 1414 'Note that neither "and" nor "or" restrict the value and type ' | |
| 1415 'they\n' | |
| 1416 'return to "False" and "True", but rather return the last ' | |
| 1417 'evaluated\n' | |
| 1418 'argument. This is sometimes useful, e.g., if "s" is a string ' | |
| 1419 'that\n' | |
| 1420 'should be replaced by a default value if it is empty, the ' | |
| 1421 'expression\n' | |
| 1422 '"s or \'foo\'" yields the desired value. Because "not" has to ' | |
| 1423 'create a\n' | |
| 1424 'new value, it returns a boolean value regardless of the type of ' | |
| 1425 'its\n' | |
| 1426 'argument (for example, "not \'foo\'" produces "False" rather ' | |
| 1427 'than "\'\'".)\n', | |
| 1428 'break': 'The "break" statement\n' | |
| 1429 '*********************\n' | |
| 1430 '\n' | |
| 1431 ' break_stmt ::= "break"\n' | |
| 1432 '\n' | |
| 1433 '"break" may only occur syntactically nested in a "for" or "while"\n' | |
| 1434 'loop, but not nested in a function or class definition within that\n' | |
| 1435 'loop.\n' | |
| 1436 '\n' | |
| 1437 'It terminates the nearest enclosing loop, skipping the optional ' | |
| 1438 '"else"\n' | |
| 1439 'clause if the loop has one.\n' | |
| 1440 '\n' | |
| 1441 'If a "for" loop is terminated by "break", the loop control target\n' | |
| 1442 'keeps its current value.\n' | |
| 1443 '\n' | |
| 1444 'When "break" passes control out of a "try" statement with a ' | |
| 1445 '"finally"\n' | |
| 1446 'clause, that "finally" clause is executed before really leaving ' | |
| 1447 'the\n' | |
| 1448 'loop.\n', | |
| 1449 'callable-types': 'Emulating callable objects\n' | |
| 1450 '**************************\n' | |
| 1451 '\n' | |
| 1452 'object.__call__(self[, args...])\n' | |
| 1453 '\n' | |
| 1454 ' Called when the instance is “called” as a function; if ' | |
| 1455 'this method\n' | |
| 1456 ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' | |
| 1457 ' "x.__call__(arg1, arg2, ...)".\n', | |
| 1458 'calls': 'Calls\n' | |
| 1459 '*****\n' | |
| 1460 '\n' | |
| 1461 'A call calls a callable object (e.g., a *function*) with a ' | |
| 1462 'possibly\n' | |
| 1463 'empty series of *arguments*:\n' | |
| 1464 '\n' | |
| 1465 ' call ::= primary "(" [argument_list [","] | ' | |
| 1466 'comprehension] ")"\n' | |
| 1467 ' argument_list ::= positional_arguments ["," ' | |
| 1468 'starred_and_keywords]\n' | |
| 1469 ' ["," keywords_arguments]\n' | |
| 1470 ' | starred_and_keywords ["," ' | |
| 1471 'keywords_arguments]\n' | |
| 1472 ' | keywords_arguments\n' | |
| 1473 ' positional_arguments ::= ["*"] expression ("," ["*"] ' | |
| 1474 'expression)*\n' | |
| 1475 ' starred_and_keywords ::= ("*" expression | keyword_item)\n' | |
| 1476 ' ("," "*" expression | "," ' | |
| 1477 'keyword_item)*\n' | |
| 1478 ' keywords_arguments ::= (keyword_item | "**" expression)\n' | |
| 1479 ' ("," keyword_item | "," "**" ' | |
| 1480 'expression)*\n' | |
| 1481 ' keyword_item ::= identifier "=" expression\n' | |
| 1482 '\n' | |
| 1483 'An optional trailing comma may be present after the positional and\n' | |
| 1484 'keyword arguments but does not affect the semantics.\n' | |
| 1485 '\n' | |
| 1486 'The primary must evaluate to a callable object (user-defined\n' | |
| 1487 'functions, built-in functions, methods of built-in objects, class\n' | |
| 1488 'objects, methods of class instances, and all objects having a\n' | |
| 1489 '"__call__()" method are callable). All argument expressions are\n' | |
| 1490 'evaluated before the call is attempted. Please refer to section\n' | |
| 1491 'Function definitions for the syntax of formal *parameter* lists.\n' | |
| 1492 '\n' | |
| 1493 'If keyword arguments are present, they are first converted to\n' | |
| 1494 'positional arguments, as follows. First, a list of unfilled slots ' | |
| 1495 'is\n' | |
| 1496 'created for the formal parameters. If there are N positional\n' | |
| 1497 'arguments, they are placed in the first N slots. Next, for each\n' | |
| 1498 'keyword argument, the identifier is used to determine the\n' | |
| 1499 'corresponding slot (if the identifier is the same as the first ' | |
| 1500 'formal\n' | |
| 1501 'parameter name, the first slot is used, and so on). If the slot ' | |
| 1502 'is\n' | |
| 1503 'already filled, a "TypeError" exception is raised. Otherwise, the\n' | |
| 1504 'value of the argument is placed in the slot, filling it (even if ' | |
| 1505 'the\n' | |
| 1506 'expression is "None", it fills the slot). When all arguments have\n' | |
| 1507 'been processed, the slots that are still unfilled are filled with ' | |
| 1508 'the\n' | |
| 1509 'corresponding default value from the function definition. ' | |
| 1510 '(Default\n' | |
| 1511 'values are calculated, once, when the function is defined; thus, a\n' | |
| 1512 'mutable object such as a list or dictionary used as default value ' | |
| 1513 'will\n' | |
| 1514 'be shared by all calls that don’t specify an argument value for ' | |
| 1515 'the\n' | |
| 1516 'corresponding slot; this should usually be avoided.) If there are ' | |
| 1517 'any\n' | |
| 1518 'unfilled slots for which no default value is specified, a ' | |
| 1519 '"TypeError"\n' | |
| 1520 'exception is raised. Otherwise, the list of filled slots is used ' | |
| 1521 'as\n' | |
| 1522 'the argument list for the call.\n' | |
| 1523 '\n' | |
| 1524 '**CPython implementation detail:** An implementation may provide\n' | |
| 1525 'built-in functions whose positional parameters do not have names, ' | |
| 1526 'even\n' | |
| 1527 'if they are ‘named’ for the purpose of documentation, and which\n' | |
| 1528 'therefore cannot be supplied by keyword. In CPython, this is the ' | |
| 1529 'case\n' | |
| 1530 'for functions implemented in C that use "PyArg_ParseTuple()" to ' | |
| 1531 'parse\n' | |
| 1532 'their arguments.\n' | |
| 1533 '\n' | |
| 1534 'If there are more positional arguments than there are formal ' | |
| 1535 'parameter\n' | |
| 1536 'slots, a "TypeError" exception is raised, unless a formal ' | |
| 1537 'parameter\n' | |
| 1538 'using the syntax "*identifier" is present; in this case, that ' | |
| 1539 'formal\n' | |
| 1540 'parameter receives a tuple containing the excess positional ' | |
| 1541 'arguments\n' | |
| 1542 '(or an empty tuple if there were no excess positional arguments).\n' | |
| 1543 '\n' | |
| 1544 'If any keyword argument does not correspond to a formal parameter\n' | |
| 1545 'name, a "TypeError" exception is raised, unless a formal parameter\n' | |
| 1546 'using the syntax "**identifier" is present; in this case, that ' | |
| 1547 'formal\n' | |
| 1548 'parameter receives a dictionary containing the excess keyword\n' | |
| 1549 'arguments (using the keywords as keys and the argument values as\n' | |
| 1550 'corresponding values), or a (new) empty dictionary if there were ' | |
| 1551 'no\n' | |
| 1552 'excess keyword arguments.\n' | |
| 1553 '\n' | |
| 1554 'If the syntax "*expression" appears in the function call, ' | |
| 1555 '"expression"\n' | |
| 1556 'must evaluate to an *iterable*. Elements from these iterables are\n' | |
| 1557 'treated as if they were additional positional arguments. For the ' | |
| 1558 'call\n' | |
| 1559 '"f(x1, x2, *y, x3, x4)", if *y* evaluates to a sequence *y1*, …, ' | |
| 1560 '*yM*,\n' | |
| 1561 'this is equivalent to a call with M+4 positional arguments *x1*, ' | |
| 1562 '*x2*,\n' | |
| 1563 '*y1*, …, *yM*, *x3*, *x4*.\n' | |
| 1564 '\n' | |
| 1565 'A consequence of this is that although the "*expression" syntax ' | |
| 1566 'may\n' | |
| 1567 'appear *after* explicit keyword arguments, it is processed ' | |
| 1568 '*before*\n' | |
| 1569 'the keyword arguments (and any "**expression" arguments – see ' | |
| 1570 'below).\n' | |
| 1571 'So:\n' | |
| 1572 '\n' | |
| 1573 ' >>> def f(a, b):\n' | |
| 1574 ' ... print(a, b)\n' | |
| 1575 ' ...\n' | |
| 1576 ' >>> f(b=1, *(2,))\n' | |
| 1577 ' 2 1\n' | |
| 1578 ' >>> f(a=1, *(2,))\n' | |
| 1579 ' Traceback (most recent call last):\n' | |
| 1580 ' File "<stdin>", line 1, in <module>\n' | |
| 1581 " TypeError: f() got multiple values for keyword argument 'a'\n" | |
| 1582 ' >>> f(1, *(2,))\n' | |
| 1583 ' 1 2\n' | |
| 1584 '\n' | |
| 1585 'It is unusual for both keyword arguments and the "*expression" ' | |
| 1586 'syntax\n' | |
| 1587 'to be used in the same call, so in practice this confusion does ' | |
| 1588 'not\n' | |
| 1589 'arise.\n' | |
| 1590 '\n' | |
| 1591 'If the syntax "**expression" appears in the function call,\n' | |
| 1592 '"expression" must evaluate to a *mapping*, the contents of which ' | |
| 1593 'are\n' | |
| 1594 'treated as additional keyword arguments. If a keyword is already\n' | |
| 1595 'present (as an explicit keyword argument, or from another ' | |
| 1596 'unpacking),\n' | |
| 1597 'a "TypeError" exception is raised.\n' | |
| 1598 '\n' | |
| 1599 'Formal parameters using the syntax "*identifier" or "**identifier"\n' | |
| 1600 'cannot be used as positional argument slots or as keyword argument\n' | |
| 1601 'names.\n' | |
| 1602 '\n' | |
| 1603 'Changed in version 3.5: Function calls accept any number of "*" ' | |
| 1604 'and\n' | |
| 1605 '"**" unpackings, positional arguments may follow iterable ' | |
| 1606 'unpackings\n' | |
| 1607 '("*"), and keyword arguments may follow dictionary unpackings ' | |
| 1608 '("**").\n' | |
| 1609 'Originally proposed by **PEP 448**.\n' | |
| 1610 '\n' | |
| 1611 'A call always returns some value, possibly "None", unless it raises ' | |
| 1612 'an\n' | |
| 1613 'exception. How this value is computed depends on the type of the\n' | |
| 1614 'callable object.\n' | |
| 1615 '\n' | |
| 1616 'If it is—\n' | |
| 1617 '\n' | |
| 1618 'a user-defined function:\n' | |
| 1619 ' The code block for the function is executed, passing it the\n' | |
| 1620 ' argument list. The first thing the code block will do is bind ' | |
| 1621 'the\n' | |
| 1622 ' formal parameters to the arguments; this is described in ' | |
| 1623 'section\n' | |
| 1624 ' Function definitions. When the code block executes a "return"\n' | |
| 1625 ' statement, this specifies the return value of the function ' | |
| 1626 'call.\n' | |
| 1627 '\n' | |
| 1628 'a built-in function or method:\n' | |
| 1629 ' The result is up to the interpreter; see Built-in Functions for ' | |
| 1630 'the\n' | |
| 1631 ' descriptions of built-in functions and methods.\n' | |
| 1632 '\n' | |
| 1633 'a class object:\n' | |
| 1634 ' A new instance of that class is returned.\n' | |
| 1635 '\n' | |
| 1636 'a class instance method:\n' | |
| 1637 ' The corresponding user-defined function is called, with an ' | |
| 1638 'argument\n' | |
| 1639 ' list that is one longer than the argument list of the call: the\n' | |
| 1640 ' instance becomes the first argument.\n' | |
| 1641 '\n' | |
| 1642 'a class instance:\n' | |
| 1643 ' The class must define a "__call__()" method; the effect is then ' | |
| 1644 'the\n' | |
| 1645 ' same as if that method was called.\n', | |
| 1646 'class': 'Class definitions\n' | |
| 1647 '*****************\n' | |
| 1648 '\n' | |
| 1649 'A class definition defines a class object (see section The ' | |
| 1650 'standard\n' | |
| 1651 'type hierarchy):\n' | |
| 1652 '\n' | |
| 1653 ' classdef ::= [decorators] "class" classname [inheritance] ":" ' | |
| 1654 'suite\n' | |
| 1655 ' inheritance ::= "(" [argument_list] ")"\n' | |
| 1656 ' classname ::= identifier\n' | |
| 1657 '\n' | |
| 1658 'A class definition is an executable statement. The inheritance ' | |
| 1659 'list\n' | |
| 1660 'usually gives a list of base classes (see Metaclasses for more\n' | |
| 1661 'advanced uses), so each item in the list should evaluate to a ' | |
| 1662 'class\n' | |
| 1663 'object which allows subclassing. Classes without an inheritance ' | |
| 1664 'list\n' | |
| 1665 'inherit, by default, from the base class "object"; hence,\n' | |
| 1666 '\n' | |
| 1667 ' class Foo:\n' | |
| 1668 ' pass\n' | |
| 1669 '\n' | |
| 1670 'is equivalent to\n' | |
| 1671 '\n' | |
| 1672 ' class Foo(object):\n' | |
| 1673 ' pass\n' | |
| 1674 '\n' | |
| 1675 'The class’s suite is then executed in a new execution frame (see\n' | |
| 1676 'Naming and binding), using a newly created local namespace and the\n' | |
| 1677 'original global namespace. (Usually, the suite contains mostly\n' | |
| 1678 'function definitions.) When the class’s suite finishes execution, ' | |
| 1679 'its\n' | |
| 1680 'execution frame is discarded but its local namespace is saved. [3] ' | |
| 1681 'A\n' | |
| 1682 'class object is then created using the inheritance list for the ' | |
| 1683 'base\n' | |
| 1684 'classes and the saved local namespace for the attribute ' | |
| 1685 'dictionary.\n' | |
| 1686 'The class name is bound to this class object in the original local\n' | |
| 1687 'namespace.\n' | |
| 1688 '\n' | |
| 1689 'The order in which attributes are defined in the class body is\n' | |
| 1690 'preserved in the new class’s "__dict__". Note that this is ' | |
| 1691 'reliable\n' | |
| 1692 'only right after the class is created and only for classes that ' | |
| 1693 'were\n' | |
| 1694 'defined using the definition syntax.\n' | |
| 1695 '\n' | |
| 1696 'Class creation can be customized heavily using metaclasses.\n' | |
| 1697 '\n' | |
| 1698 'Classes can also be decorated: just like when decorating ' | |
| 1699 'functions,\n' | |
| 1700 '\n' | |
| 1701 ' @f1(arg)\n' | |
| 1702 ' @f2\n' | |
| 1703 ' class Foo: pass\n' | |
| 1704 '\n' | |
| 1705 'is roughly equivalent to\n' | |
| 1706 '\n' | |
| 1707 ' class Foo: pass\n' | |
| 1708 ' Foo = f1(arg)(f2(Foo))\n' | |
| 1709 '\n' | |
| 1710 'The evaluation rules for the decorator expressions are the same as ' | |
| 1711 'for\n' | |
| 1712 'function decorators. The result is then bound to the class name.\n' | |
| 1713 '\n' | |
| 1714 '**Programmer’s note:** Variables defined in the class definition ' | |
| 1715 'are\n' | |
| 1716 'class attributes; they are shared by instances. Instance ' | |
| 1717 'attributes\n' | |
| 1718 'can be set in a method with "self.name = value". Both class and\n' | |
| 1719 'instance attributes are accessible through the notation ' | |
| 1720 '“"self.name"”,\n' | |
| 1721 'and an instance attribute hides a class attribute with the same ' | |
| 1722 'name\n' | |
| 1723 'when accessed in this way. Class attributes can be used as ' | |
| 1724 'defaults\n' | |
| 1725 'for instance attributes, but using mutable values there can lead ' | |
| 1726 'to\n' | |
| 1727 'unexpected results. Descriptors can be used to create instance\n' | |
| 1728 'variables with different implementation details.\n' | |
| 1729 '\n' | |
| 1730 'See also:\n' | |
| 1731 '\n' | |
| 1732 ' **PEP 3115** - Metaclasses in Python 3000\n' | |
| 1733 ' The proposal that changed the declaration of metaclasses to ' | |
| 1734 'the\n' | |
| 1735 ' current syntax, and the semantics for how classes with\n' | |
| 1736 ' metaclasses are constructed.\n' | |
| 1737 '\n' | |
| 1738 ' **PEP 3129** - Class Decorators\n' | |
| 1739 ' The proposal that added class decorators. Function and ' | |
| 1740 'method\n' | |
| 1741 ' decorators were introduced in **PEP 318**.\n', | |
| 1742 'comparisons': 'Comparisons\n' | |
| 1743 '***********\n' | |
| 1744 '\n' | |
| 1745 'Unlike C, all comparison operations in Python have the same ' | |
| 1746 'priority,\n' | |
| 1747 'which is lower than that of any arithmetic, shifting or ' | |
| 1748 'bitwise\n' | |
| 1749 'operation. Also unlike C, expressions like "a < b < c" have ' | |
| 1750 'the\n' | |
| 1751 'interpretation that is conventional in mathematics:\n' | |
| 1752 '\n' | |
| 1753 ' comparison ::= or_expr (comp_operator or_expr)*\n' | |
| 1754 ' comp_operator ::= "<" | ">" | "==" | ">=" | "<=" | "!="\n' | |
| 1755 ' | "is" ["not"] | ["not"] "in"\n' | |
| 1756 '\n' | |
| 1757 'Comparisons yield boolean values: "True" or "False".\n' | |
| 1758 '\n' | |
| 1759 'Comparisons can be chained arbitrarily, e.g., "x < y <= z" ' | |
| 1760 'is\n' | |
| 1761 'equivalent to "x < y and y <= z", except that "y" is ' | |
| 1762 'evaluated only\n' | |
| 1763 'once (but in both cases "z" is not evaluated at all when "x < ' | |
| 1764 'y" is\n' | |
| 1765 'found to be false).\n' | |
| 1766 '\n' | |
| 1767 'Formally, if *a*, *b*, *c*, …, *y*, *z* are expressions and ' | |
| 1768 '*op1*,\n' | |
| 1769 '*op2*, …, *opN* are comparison operators, then "a op1 b op2 c ' | |
| 1770 '... y\n' | |
| 1771 'opN z" is equivalent to "a op1 b and b op2 c and ... y opN ' | |
| 1772 'z", except\n' | |
| 1773 'that each expression is evaluated at most once.\n' | |
| 1774 '\n' | |
| 1775 'Note that "a op1 b op2 c" doesn’t imply any kind of ' | |
| 1776 'comparison between\n' | |
| 1777 '*a* and *c*, so that, e.g., "x < y > z" is perfectly legal ' | |
| 1778 '(though\n' | |
| 1779 'perhaps not pretty).\n' | |
| 1780 '\n' | |
| 1781 '\n' | |
| 1782 'Value comparisons\n' | |
| 1783 '=================\n' | |
| 1784 '\n' | |
| 1785 'The operators "<", ">", "==", ">=", "<=", and "!=" compare ' | |
| 1786 'the values\n' | |
| 1787 'of two objects. The objects do not need to have the same ' | |
| 1788 'type.\n' | |
| 1789 '\n' | |
| 1790 'Chapter Objects, values and types states that objects have a ' | |
| 1791 'value (in\n' | |
| 1792 'addition to type and identity). The value of an object is a ' | |
| 1793 'rather\n' | |
| 1794 'abstract notion in Python: For example, there is no canonical ' | |
| 1795 'access\n' | |
| 1796 'method for an object’s value. Also, there is no requirement ' | |
| 1797 'that the\n' | |
| 1798 'value of an object should be constructed in a particular way, ' | |
| 1799 'e.g.\n' | |
| 1800 'comprised of all its data attributes. Comparison operators ' | |
| 1801 'implement a\n' | |
| 1802 'particular notion of what the value of an object is. One can ' | |
| 1803 'think of\n' | |
| 1804 'them as defining the value of an object indirectly, by means ' | |
| 1805 'of their\n' | |
| 1806 'comparison implementation.\n' | |
| 1807 '\n' | |
| 1808 'Because all types are (direct or indirect) subtypes of ' | |
| 1809 '"object", they\n' | |
| 1810 'inherit the default comparison behavior from "object". Types ' | |
| 1811 'can\n' | |
| 1812 'customize their comparison behavior by implementing *rich ' | |
| 1813 'comparison\n' | |
| 1814 'methods* like "__lt__()", described in Basic customization.\n' | |
| 1815 '\n' | |
| 1816 'The default behavior for equality comparison ("==" and "!=") ' | |
| 1817 'is based\n' | |
| 1818 'on the identity of the objects. Hence, equality comparison ' | |
| 1819 'of\n' | |
| 1820 'instances with the same identity results in equality, and ' | |
| 1821 'equality\n' | |
| 1822 'comparison of instances with different identities results in\n' | |
| 1823 'inequality. A motivation for this default behavior is the ' | |
| 1824 'desire that\n' | |
| 1825 'all objects should be reflexive (i.e. "x is y" implies "x == ' | |
| 1826 'y").\n' | |
| 1827 '\n' | |
| 1828 'A default order comparison ("<", ">", "<=", and ">=") is not ' | |
| 1829 'provided;\n' | |
| 1830 'an attempt raises "TypeError". A motivation for this default ' | |
| 1831 'behavior\n' | |
| 1832 'is the lack of a similar invariant as for equality.\n' | |
| 1833 '\n' | |
| 1834 'The behavior of the default equality comparison, that ' | |
| 1835 'instances with\n' | |
| 1836 'different identities are always unequal, may be in contrast ' | |
| 1837 'to what\n' | |
| 1838 'types will need that have a sensible definition of object ' | |
| 1839 'value and\n' | |
| 1840 'value-based equality. Such types will need to customize ' | |
| 1841 'their\n' | |
| 1842 'comparison behavior, and in fact, a number of built-in types ' | |
| 1843 'have done\n' | |
| 1844 'that.\n' | |
| 1845 '\n' | |
| 1846 'The following list describes the comparison behavior of the ' | |
| 1847 'most\n' | |
| 1848 'important built-in types.\n' | |
| 1849 '\n' | |
| 1850 '* Numbers of built-in numeric types (Numeric Types — int, ' | |
| 1851 'float,\n' | |
| 1852 ' complex) and of the standard library types ' | |
| 1853 '"fractions.Fraction" and\n' | |
| 1854 ' "decimal.Decimal" can be compared within and across their ' | |
| 1855 'types,\n' | |
| 1856 ' with the restriction that complex numbers do not support ' | |
| 1857 'order\n' | |
| 1858 ' comparison. Within the limits of the types involved, they ' | |
| 1859 'compare\n' | |
| 1860 ' mathematically (algorithmically) correct without loss of ' | |
| 1861 'precision.\n' | |
| 1862 '\n' | |
| 1863 ' The not-a-number values "float(\'NaN\')" and ' | |
| 1864 '"decimal.Decimal(\'NaN\')"\n' | |
| 1865 ' are special. Any ordered comparison of a number to a ' | |
| 1866 'not-a-number\n' | |
| 1867 ' value is false. A counter-intuitive implication is that ' | |
| 1868 'not-a-number\n' | |
| 1869 ' values are not equal to themselves. For example, if "x =\n' | |
| 1870 ' float(\'NaN\')", "3 < x", "x < 3", "x == x", "x != x" are ' | |
| 1871 'all false.\n' | |
| 1872 ' This behavior is compliant with IEEE 754.\n' | |
| 1873 '\n' | |
| 1874 '* "None" and "NotImplemented" are singletons. **PEP 8** ' | |
| 1875 'advises\n' | |
| 1876 ' that comparisons for singletons should always be done with ' | |
| 1877 '"is" or\n' | |
| 1878 ' "is not", never the equality operators.\n' | |
| 1879 '\n' | |
| 1880 '* Binary sequences (instances of "bytes" or "bytearray") can ' | |
| 1881 'be\n' | |
| 1882 ' compared within and across their types. They compare\n' | |
| 1883 ' lexicographically using the numeric values of their ' | |
| 1884 'elements.\n' | |
| 1885 '\n' | |
| 1886 '* Strings (instances of "str") compare lexicographically ' | |
| 1887 'using the\n' | |
| 1888 ' numerical Unicode code points (the result of the built-in ' | |
| 1889 'function\n' | |
| 1890 ' "ord()") of their characters. [3]\n' | |
| 1891 '\n' | |
| 1892 ' Strings and binary sequences cannot be directly compared.\n' | |
| 1893 '\n' | |
| 1894 '* Sequences (instances of "tuple", "list", or "range") can ' | |
| 1895 'be\n' | |
| 1896 ' compared only within each of their types, with the ' | |
| 1897 'restriction that\n' | |
| 1898 ' ranges do not support order comparison. Equality ' | |
| 1899 'comparison across\n' | |
| 1900 ' these types results in inequality, and ordering comparison ' | |
| 1901 'across\n' | |
| 1902 ' these types raises "TypeError".\n' | |
| 1903 '\n' | |
| 1904 ' Sequences compare lexicographically using comparison of\n' | |
| 1905 ' corresponding elements. The built-in containers typically ' | |
| 1906 'assume\n' | |
| 1907 ' identical objects are equal to themselves. That lets them ' | |
| 1908 'bypass\n' | |
| 1909 ' equality tests for identical objects to improve performance ' | |
| 1910 'and to\n' | |
| 1911 ' maintain their internal invariants.\n' | |
| 1912 '\n' | |
| 1913 ' Lexicographical comparison between built-in collections ' | |
| 1914 'works as\n' | |
| 1915 ' follows:\n' | |
| 1916 '\n' | |
| 1917 ' * For two collections to compare equal, they must be of the ' | |
| 1918 'same\n' | |
| 1919 ' type, have the same length, and each pair of ' | |
| 1920 'corresponding\n' | |
| 1921 ' elements must compare equal (for example, "[1,2] == ' | |
| 1922 '(1,2)" is\n' | |
| 1923 ' false because the type is not the same).\n' | |
| 1924 '\n' | |
| 1925 ' * Collections that support order comparison are ordered the ' | |
| 1926 'same\n' | |
| 1927 ' as their first unequal elements (for example, "[1,2,x] <= ' | |
| 1928 '[1,2,y]"\n' | |
| 1929 ' has the same value as "x <= y"). If a corresponding ' | |
| 1930 'element does\n' | |
| 1931 ' not exist, the shorter collection is ordered first (for ' | |
| 1932 'example,\n' | |
| 1933 ' "[1,2] < [1,2,3]" is true).\n' | |
| 1934 '\n' | |
| 1935 '* Mappings (instances of "dict") compare equal if and only if ' | |
| 1936 'they\n' | |
| 1937 ' have equal *(key, value)* pairs. Equality comparison of the ' | |
| 1938 'keys and\n' | |
| 1939 ' values enforces reflexivity.\n' | |
| 1940 '\n' | |
| 1941 ' Order comparisons ("<", ">", "<=", and ">=") raise ' | |
| 1942 '"TypeError".\n' | |
| 1943 '\n' | |
| 1944 '* Sets (instances of "set" or "frozenset") can be compared ' | |
| 1945 'within\n' | |
| 1946 ' and across their types.\n' | |
| 1947 '\n' | |
| 1948 ' They define order comparison operators to mean subset and ' | |
| 1949 'superset\n' | |
| 1950 ' tests. Those relations do not define total orderings (for ' | |
| 1951 'example,\n' | |
| 1952 ' the two sets "{1,2}" and "{2,3}" are not equal, nor subsets ' | |
| 1953 'of one\n' | |
| 1954 ' another, nor supersets of one another). Accordingly, sets ' | |
| 1955 'are not\n' | |
| 1956 ' appropriate arguments for functions which depend on total ' | |
| 1957 'ordering\n' | |
| 1958 ' (for example, "min()", "max()", and "sorted()" produce ' | |
| 1959 'undefined\n' | |
| 1960 ' results given a list of sets as inputs).\n' | |
| 1961 '\n' | |
| 1962 ' Comparison of sets enforces reflexivity of its elements.\n' | |
| 1963 '\n' | |
| 1964 '* Most other built-in types have no comparison methods ' | |
| 1965 'implemented,\n' | |
| 1966 ' so they inherit the default comparison behavior.\n' | |
| 1967 '\n' | |
| 1968 'User-defined classes that customize their comparison behavior ' | |
| 1969 'should\n' | |
| 1970 'follow some consistency rules, if possible:\n' | |
| 1971 '\n' | |
| 1972 '* Equality comparison should be reflexive. In other words, ' | |
| 1973 'identical\n' | |
| 1974 ' objects should compare equal:\n' | |
| 1975 '\n' | |
| 1976 ' "x is y" implies "x == y"\n' | |
| 1977 '\n' | |
| 1978 '* Comparison should be symmetric. In other words, the ' | |
| 1979 'following\n' | |
| 1980 ' expressions should have the same result:\n' | |
| 1981 '\n' | |
| 1982 ' "x == y" and "y == x"\n' | |
| 1983 '\n' | |
| 1984 ' "x != y" and "y != x"\n' | |
| 1985 '\n' | |
| 1986 ' "x < y" and "y > x"\n' | |
| 1987 '\n' | |
| 1988 ' "x <= y" and "y >= x"\n' | |
| 1989 '\n' | |
| 1990 '* Comparison should be transitive. The following ' | |
| 1991 '(non-exhaustive)\n' | |
| 1992 ' examples illustrate that:\n' | |
| 1993 '\n' | |
| 1994 ' "x > y and y > z" implies "x > z"\n' | |
| 1995 '\n' | |
| 1996 ' "x < y and y <= z" implies "x < z"\n' | |
| 1997 '\n' | |
| 1998 '* Inverse comparison should result in the boolean negation. ' | |
| 1999 'In other\n' | |
| 2000 ' words, the following expressions should have the same ' | |
| 2001 'result:\n' | |
| 2002 '\n' | |
| 2003 ' "x == y" and "not x != y"\n' | |
| 2004 '\n' | |
| 2005 ' "x < y" and "not x >= y" (for total ordering)\n' | |
| 2006 '\n' | |
| 2007 ' "x > y" and "not x <= y" (for total ordering)\n' | |
| 2008 '\n' | |
| 2009 ' The last two expressions apply to totally ordered ' | |
| 2010 'collections (e.g.\n' | |
| 2011 ' to sequences, but not to sets or mappings). See also the\n' | |
| 2012 ' "total_ordering()" decorator.\n' | |
| 2013 '\n' | |
| 2014 '* The "hash()" result should be consistent with equality. ' | |
| 2015 'Objects\n' | |
| 2016 ' that are equal should either have the same hash value, or ' | |
| 2017 'be marked\n' | |
| 2018 ' as unhashable.\n' | |
| 2019 '\n' | |
| 2020 'Python does not enforce these consistency rules. In fact, ' | |
| 2021 'the\n' | |
| 2022 'not-a-number values are an example for not following these ' | |
| 2023 'rules.\n' | |
| 2024 '\n' | |
| 2025 '\n' | |
| 2026 'Membership test operations\n' | |
| 2027 '==========================\n' | |
| 2028 '\n' | |
| 2029 'The operators "in" and "not in" test for membership. "x in ' | |
| 2030 's"\n' | |
| 2031 'evaluates to "True" if *x* is a member of *s*, and "False" ' | |
| 2032 'otherwise.\n' | |
| 2033 '"x not in s" returns the negation of "x in s". All built-in ' | |
| 2034 'sequences\n' | |
| 2035 'and set types support this as well as dictionary, for which ' | |
| 2036 '"in" tests\n' | |
| 2037 'whether the dictionary has a given key. For container types ' | |
| 2038 'such as\n' | |
| 2039 'list, tuple, set, frozenset, dict, or collections.deque, the\n' | |
| 2040 'expression "x in y" is equivalent to "any(x is e or x == e ' | |
| 2041 'for e in\n' | |
| 2042 'y)".\n' | |
| 2043 '\n' | |
| 2044 'For the string and bytes types, "x in y" is "True" if and ' | |
| 2045 'only if *x*\n' | |
| 2046 'is a substring of *y*. An equivalent test is "y.find(x) != ' | |
| 2047 '-1".\n' | |
| 2048 'Empty strings are always considered to be a substring of any ' | |
| 2049 'other\n' | |
| 2050 'string, so """ in "abc"" will return "True".\n' | |
| 2051 '\n' | |
| 2052 'For user-defined classes which define the "__contains__()" ' | |
| 2053 'method, "x\n' | |
| 2054 'in y" returns "True" if "y.__contains__(x)" returns a true ' | |
| 2055 'value, and\n' | |
| 2056 '"False" otherwise.\n' | |
| 2057 '\n' | |
| 2058 'For user-defined classes which do not define "__contains__()" ' | |
| 2059 'but do\n' | |
| 2060 'define "__iter__()", "x in y" is "True" if some value "z", ' | |
| 2061 'for which\n' | |
| 2062 'the expression "x is z or x == z" is true, is produced while ' | |
| 2063 'iterating\n' | |
| 2064 'over "y". If an exception is raised during the iteration, it ' | |
| 2065 'is as if\n' | |
| 2066 '"in" raised that exception.\n' | |
| 2067 '\n' | |
| 2068 'Lastly, the old-style iteration protocol is tried: if a class ' | |
| 2069 'defines\n' | |
| 2070 '"__getitem__()", "x in y" is "True" if and only if there is a ' | |
| 2071 'non-\n' | |
| 2072 'negative integer index *i* such that "x is y[i] or x == ' | |
| 2073 'y[i]", and no\n' | |
| 2074 'lower integer index raises the "IndexError" exception. (If ' | |
| 2075 'any other\n' | |
| 2076 'exception is raised, it is as if "in" raised that ' | |
| 2077 'exception).\n' | |
| 2078 '\n' | |
| 2079 'The operator "not in" is defined to have the inverse truth ' | |
| 2080 'value of\n' | |
| 2081 '"in".\n' | |
| 2082 '\n' | |
| 2083 '\n' | |
| 2084 'Identity comparisons\n' | |
| 2085 '====================\n' | |
| 2086 '\n' | |
| 2087 'The operators "is" and "is not" test for an object’s ' | |
| 2088 'identity: "x is\n' | |
| 2089 'y" is true if and only if *x* and *y* are the same object. ' | |
| 2090 'An\n' | |
| 2091 'Object’s identity is determined using the "id()" function. ' | |
| 2092 '"x is not\n' | |
| 2093 'y" yields the inverse truth value. [4]\n', | |
| 2094 'compound': 'Compound statements\n' | |
| 2095 '*******************\n' | |
| 2096 '\n' | |
| 2097 'Compound statements contain (groups of) other statements; they ' | |
| 2098 'affect\n' | |
| 2099 'or control the execution of those other statements in some way. ' | |
| 2100 'In\n' | |
| 2101 'general, compound statements span multiple lines, although in ' | |
| 2102 'simple\n' | |
| 2103 'incarnations a whole compound statement may be contained in one ' | |
| 2104 'line.\n' | |
| 2105 '\n' | |
| 2106 'The "if", "while" and "for" statements implement traditional ' | |
| 2107 'control\n' | |
| 2108 'flow constructs. "try" specifies exception handlers and/or ' | |
| 2109 'cleanup\n' | |
| 2110 'code for a group of statements, while the "with" statement ' | |
| 2111 'allows the\n' | |
| 2112 'execution of initialization and finalization code around a block ' | |
| 2113 'of\n' | |
| 2114 'code. Function and class definitions are also syntactically ' | |
| 2115 'compound\n' | |
| 2116 'statements.\n' | |
| 2117 '\n' | |
| 2118 'A compound statement consists of one or more ‘clauses.’ A ' | |
| 2119 'clause\n' | |
| 2120 'consists of a header and a ‘suite.’ The clause headers of a\n' | |
| 2121 'particular compound statement are all at the same indentation ' | |
| 2122 'level.\n' | |
| 2123 'Each clause header begins with a uniquely identifying keyword ' | |
| 2124 'and ends\n' | |
| 2125 'with a colon. A suite is a group of statements controlled by a\n' | |
| 2126 'clause. A suite can be one or more semicolon-separated simple\n' | |
| 2127 'statements on the same line as the header, following the ' | |
| 2128 'header’s\n' | |
| 2129 'colon, or it can be one or more indented statements on ' | |
| 2130 'subsequent\n' | |
| 2131 'lines. Only the latter form of a suite can contain nested ' | |
| 2132 'compound\n' | |
| 2133 'statements; the following is illegal, mostly because it wouldn’t ' | |
| 2134 'be\n' | |
| 2135 'clear to which "if" clause a following "else" clause would ' | |
| 2136 'belong:\n' | |
| 2137 '\n' | |
| 2138 ' if test1: if test2: print(x)\n' | |
| 2139 '\n' | |
| 2140 'Also note that the semicolon binds tighter than the colon in ' | |
| 2141 'this\n' | |
| 2142 'context, so that in the following example, either all or none of ' | |
| 2143 'the\n' | |
| 2144 '"print()" calls are executed:\n' | |
| 2145 '\n' | |
| 2146 ' if x < y < z: print(x); print(y); print(z)\n' | |
| 2147 '\n' | |
| 2148 'Summarizing:\n' | |
| 2149 '\n' | |
| 2150 ' compound_stmt ::= if_stmt\n' | |
| 2151 ' | while_stmt\n' | |
| 2152 ' | for_stmt\n' | |
| 2153 ' | try_stmt\n' | |
| 2154 ' | with_stmt\n' | |
| 2155 ' | funcdef\n' | |
| 2156 ' | classdef\n' | |
| 2157 ' | async_with_stmt\n' | |
| 2158 ' | async_for_stmt\n' | |
| 2159 ' | async_funcdef\n' | |
| 2160 ' suite ::= stmt_list NEWLINE | NEWLINE INDENT ' | |
| 2161 'statement+ DEDENT\n' | |
| 2162 ' statement ::= stmt_list NEWLINE | compound_stmt\n' | |
| 2163 ' stmt_list ::= simple_stmt (";" simple_stmt)* [";"]\n' | |
| 2164 '\n' | |
| 2165 'Note that statements always end in a "NEWLINE" possibly followed ' | |
| 2166 'by a\n' | |
| 2167 '"DEDENT". Also note that optional continuation clauses always ' | |
| 2168 'begin\n' | |
| 2169 'with a keyword that cannot start a statement, thus there are no\n' | |
| 2170 'ambiguities (the ‘dangling "else"’ problem is solved in Python ' | |
| 2171 'by\n' | |
| 2172 'requiring nested "if" statements to be indented).\n' | |
| 2173 '\n' | |
| 2174 'The formatting of the grammar rules in the following sections ' | |
| 2175 'places\n' | |
| 2176 'each clause on a separate line for clarity.\n' | |
| 2177 '\n' | |
| 2178 '\n' | |
| 2179 'The "if" statement\n' | |
| 2180 '==================\n' | |
| 2181 '\n' | |
| 2182 'The "if" statement is used for conditional execution:\n' | |
| 2183 '\n' | |
| 2184 ' if_stmt ::= "if" expression ":" suite\n' | |
| 2185 ' ("elif" expression ":" suite)*\n' | |
| 2186 ' ["else" ":" suite]\n' | |
| 2187 '\n' | |
| 2188 'It selects exactly one of the suites by evaluating the ' | |
| 2189 'expressions one\n' | |
| 2190 'by one until one is found to be true (see section Boolean ' | |
| 2191 'operations\n' | |
| 2192 'for the definition of true and false); then that suite is ' | |
| 2193 'executed\n' | |
| 2194 '(and no other part of the "if" statement is executed or ' | |
| 2195 'evaluated).\n' | |
| 2196 'If all expressions are false, the suite of the "else" clause, ' | |
| 2197 'if\n' | |
| 2198 'present, is executed.\n' | |
| 2199 '\n' | |
| 2200 '\n' | |
| 2201 'The "while" statement\n' | |
| 2202 '=====================\n' | |
| 2203 '\n' | |
| 2204 'The "while" statement is used for repeated execution as long as ' | |
| 2205 'an\n' | |
| 2206 'expression is true:\n' | |
| 2207 '\n' | |
| 2208 ' while_stmt ::= "while" expression ":" suite\n' | |
| 2209 ' ["else" ":" suite]\n' | |
| 2210 '\n' | |
| 2211 'This repeatedly tests the expression and, if it is true, ' | |
| 2212 'executes the\n' | |
| 2213 'first suite; if the expression is false (which may be the first ' | |
| 2214 'time\n' | |
| 2215 'it is tested) the suite of the "else" clause, if present, is ' | |
| 2216 'executed\n' | |
| 2217 'and the loop terminates.\n' | |
| 2218 '\n' | |
| 2219 'A "break" statement executed in the first suite terminates the ' | |
| 2220 'loop\n' | |
| 2221 'without executing the "else" clause’s suite. A "continue" ' | |
| 2222 'statement\n' | |
| 2223 'executed in the first suite skips the rest of the suite and goes ' | |
| 2224 'back\n' | |
| 2225 'to testing the expression.\n' | |
| 2226 '\n' | |
| 2227 '\n' | |
| 2228 'The "for" statement\n' | |
| 2229 '===================\n' | |
| 2230 '\n' | |
| 2231 'The "for" statement is used to iterate over the elements of a ' | |
| 2232 'sequence\n' | |
| 2233 '(such as a string, tuple or list) or other iterable object:\n' | |
| 2234 '\n' | |
| 2235 ' for_stmt ::= "for" target_list "in" expression_list ":" ' | |
| 2236 'suite\n' | |
| 2237 ' ["else" ":" suite]\n' | |
| 2238 '\n' | |
| 2239 'The expression list is evaluated once; it should yield an ' | |
| 2240 'iterable\n' | |
| 2241 'object. An iterator is created for the result of the\n' | |
| 2242 '"expression_list". The suite is then executed once for each ' | |
| 2243 'item\n' | |
| 2244 'provided by the iterator, in the order returned by the ' | |
| 2245 'iterator. Each\n' | |
| 2246 'item in turn is assigned to the target list using the standard ' | |
| 2247 'rules\n' | |
| 2248 'for assignments (see Assignment statements), and then the suite ' | |
| 2249 'is\n' | |
| 2250 'executed. When the items are exhausted (which is immediately ' | |
| 2251 'when the\n' | |
| 2252 'sequence is empty or an iterator raises a "StopIteration" ' | |
| 2253 'exception),\n' | |
| 2254 'the suite in the "else" clause, if present, is executed, and the ' | |
| 2255 'loop\n' | |
| 2256 'terminates.\n' | |
| 2257 '\n' | |
| 2258 'A "break" statement executed in the first suite terminates the ' | |
| 2259 'loop\n' | |
| 2260 'without executing the "else" clause’s suite. A "continue" ' | |
| 2261 'statement\n' | |
| 2262 'executed in the first suite skips the rest of the suite and ' | |
| 2263 'continues\n' | |
| 2264 'with the next item, or with the "else" clause if there is no ' | |
| 2265 'next\n' | |
| 2266 'item.\n' | |
| 2267 '\n' | |
| 2268 'The for-loop makes assignments to the variables in the target ' | |
| 2269 'list.\n' | |
| 2270 'This overwrites all previous assignments to those variables ' | |
| 2271 'including\n' | |
| 2272 'those made in the suite of the for-loop:\n' | |
| 2273 '\n' | |
| 2274 ' for i in range(10):\n' | |
| 2275 ' print(i)\n' | |
| 2276 ' i = 5 # this will not affect the for-loop\n' | |
| 2277 ' # because i will be overwritten with ' | |
| 2278 'the next\n' | |
| 2279 ' # index in the range\n' | |
| 2280 '\n' | |
| 2281 'Names in the target list are not deleted when the loop is ' | |
| 2282 'finished,\n' | |
| 2283 'but if the sequence is empty, they will not have been assigned ' | |
| 2284 'to at\n' | |
| 2285 'all by the loop. Hint: the built-in function "range()" returns ' | |
| 2286 'an\n' | |
| 2287 'iterator of integers suitable to emulate the effect of Pascal’s ' | |
| 2288 '"for i\n' | |
| 2289 ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, ' | |
| 2290 '2]".\n' | |
| 2291 '\n' | |
| 2292 'Note: There is a subtlety when the sequence is being modified by ' | |
| 2293 'the\n' | |
| 2294 ' loop (this can only occur for mutable sequences, e.g. lists). ' | |
| 2295 'An\n' | |
| 2296 ' internal counter is used to keep track of which item is used ' | |
| 2297 'next,\n' | |
| 2298 ' and this is incremented on each iteration. When this counter ' | |
| 2299 'has\n' | |
| 2300 ' reached the length of the sequence the loop terminates. This ' | |
| 2301 'means\n' | |
| 2302 ' that if the suite deletes the current (or a previous) item ' | |
| 2303 'from the\n' | |
| 2304 ' sequence, the next item will be skipped (since it gets the ' | |
| 2305 'index of\n' | |
| 2306 ' the current item which has already been treated). Likewise, ' | |
| 2307 'if the\n' | |
| 2308 ' suite inserts an item in the sequence before the current item, ' | |
| 2309 'the\n' | |
| 2310 ' current item will be treated again the next time through the ' | |
| 2311 'loop.\n' | |
| 2312 ' This can lead to nasty bugs that can be avoided by making a\n' | |
| 2313 ' temporary copy using a slice of the whole sequence, e.g.,\n' | |
| 2314 '\n' | |
| 2315 ' for x in a[:]:\n' | |
| 2316 ' if x < 0: a.remove(x)\n' | |
| 2317 '\n' | |
| 2318 '\n' | |
| 2319 'The "try" statement\n' | |
| 2320 '===================\n' | |
| 2321 '\n' | |
| 2322 'The "try" statement specifies exception handlers and/or cleanup ' | |
| 2323 'code\n' | |
| 2324 'for a group of statements:\n' | |
| 2325 '\n' | |
| 2326 ' try_stmt ::= try1_stmt | try2_stmt\n' | |
| 2327 ' try1_stmt ::= "try" ":" suite\n' | |
| 2328 ' ("except" [expression ["as" identifier]] ":" ' | |
| 2329 'suite)+\n' | |
| 2330 ' ["else" ":" suite]\n' | |
| 2331 ' ["finally" ":" suite]\n' | |
| 2332 ' try2_stmt ::= "try" ":" suite\n' | |
| 2333 ' "finally" ":" suite\n' | |
| 2334 '\n' | |
| 2335 'The "except" clause(s) specify one or more exception handlers. ' | |
| 2336 'When no\n' | |
| 2337 'exception occurs in the "try" clause, no exception handler is\n' | |
| 2338 'executed. When an exception occurs in the "try" suite, a search ' | |
| 2339 'for an\n' | |
| 2340 'exception handler is started. This search inspects the except ' | |
| 2341 'clauses\n' | |
| 2342 'in turn until one is found that matches the exception. An ' | |
| 2343 'expression-\n' | |
| 2344 'less except clause, if present, must be last; it matches any\n' | |
| 2345 'exception. For an except clause with an expression, that ' | |
| 2346 'expression\n' | |
| 2347 'is evaluated, and the clause matches the exception if the ' | |
| 2348 'resulting\n' | |
| 2349 'object is “compatible” with the exception. An object is ' | |
| 2350 'compatible\n' | |
| 2351 'with an exception if it is the class or a base class of the ' | |
| 2352 'exception\n' | |
| 2353 'object or a tuple containing an item compatible with the ' | |
| 2354 'exception.\n' | |
| 2355 '\n' | |
| 2356 'If no except clause matches the exception, the search for an ' | |
| 2357 'exception\n' | |
| 2358 'handler continues in the surrounding code and on the invocation ' | |
| 2359 'stack.\n' | |
| 2360 '[1]\n' | |
| 2361 '\n' | |
| 2362 'If the evaluation of an expression in the header of an except ' | |
| 2363 'clause\n' | |
| 2364 'raises an exception, the original search for a handler is ' | |
| 2365 'canceled and\n' | |
| 2366 'a search starts for the new exception in the surrounding code ' | |
| 2367 'and on\n' | |
| 2368 'the call stack (it is treated as if the entire "try" statement ' | |
| 2369 'raised\n' | |
| 2370 'the exception).\n' | |
| 2371 '\n' | |
| 2372 'When a matching except clause is found, the exception is ' | |
| 2373 'assigned to\n' | |
| 2374 'the target specified after the "as" keyword in that except ' | |
| 2375 'clause, if\n' | |
| 2376 'present, and the except clause’s suite is executed. All except\n' | |
| 2377 'clauses must have an executable block. When the end of this ' | |
| 2378 'block is\n' | |
| 2379 'reached, execution continues normally after the entire try ' | |
| 2380 'statement.\n' | |
| 2381 '(This means that if two nested handlers exist for the same ' | |
| 2382 'exception,\n' | |
| 2383 'and the exception occurs in the try clause of the inner handler, ' | |
| 2384 'the\n' | |
| 2385 'outer handler will not handle the exception.)\n' | |
| 2386 '\n' | |
| 2387 'When an exception has been assigned using "as target", it is ' | |
| 2388 'cleared\n' | |
| 2389 'at the end of the except clause. This is as if\n' | |
| 2390 '\n' | |
| 2391 ' except E as N:\n' | |
| 2392 ' foo\n' | |
| 2393 '\n' | |
| 2394 'was translated to\n' | |
| 2395 '\n' | |
| 2396 ' except E as N:\n' | |
| 2397 ' try:\n' | |
| 2398 ' foo\n' | |
| 2399 ' finally:\n' | |
| 2400 ' del N\n' | |
| 2401 '\n' | |
| 2402 'This means the exception must be assigned to a different name to ' | |
| 2403 'be\n' | |
| 2404 'able to refer to it after the except clause. Exceptions are ' | |
| 2405 'cleared\n' | |
| 2406 'because with the traceback attached to them, they form a ' | |
| 2407 'reference\n' | |
| 2408 'cycle with the stack frame, keeping all locals in that frame ' | |
| 2409 'alive\n' | |
| 2410 'until the next garbage collection occurs.\n' | |
| 2411 '\n' | |
| 2412 'Before an except clause’s suite is executed, details about the\n' | |
| 2413 'exception are stored in the "sys" module and can be accessed ' | |
| 2414 'via\n' | |
| 2415 '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting ' | |
| 2416 'of the\n' | |
| 2417 'exception class, the exception instance and a traceback object ' | |
| 2418 '(see\n' | |
| 2419 'section The standard type hierarchy) identifying the point in ' | |
| 2420 'the\n' | |
| 2421 'program where the exception occurred. "sys.exc_info()" values ' | |
| 2422 'are\n' | |
| 2423 'restored to their previous values (before the call) when ' | |
| 2424 'returning\n' | |
| 2425 'from a function that handled an exception.\n' | |
| 2426 '\n' | |
| 2427 'The optional "else" clause is executed if the control flow ' | |
| 2428 'leaves the\n' | |
| 2429 '"try" suite, no exception was raised, and no "return", ' | |
| 2430 '"continue", or\n' | |
| 2431 '"break" statement was executed. Exceptions in the "else" clause ' | |
| 2432 'are\n' | |
| 2433 'not handled by the preceding "except" clauses.\n' | |
| 2434 '\n' | |
| 2435 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' | |
| 2436 '"try"\n' | |
| 2437 'clause is executed, including any "except" and "else" clauses. ' | |
| 2438 'If an\n' | |
| 2439 'exception occurs in any of the clauses and is not handled, the\n' | |
| 2440 'exception is temporarily saved. The "finally" clause is ' | |
| 2441 'executed. If\n' | |
| 2442 'there is a saved exception it is re-raised at the end of the ' | |
| 2443 '"finally"\n' | |
| 2444 'clause. If the "finally" clause raises another exception, the ' | |
| 2445 'saved\n' | |
| 2446 'exception is set as the context of the new exception. If the ' | |
| 2447 '"finally"\n' | |
| 2448 'clause executes a "return", "break" or "continue" statement, the ' | |
| 2449 'saved\n' | |
| 2450 'exception is discarded:\n' | |
| 2451 '\n' | |
| 2452 ' >>> def f():\n' | |
| 2453 ' ... try:\n' | |
| 2454 ' ... 1/0\n' | |
| 2455 ' ... finally:\n' | |
| 2456 ' ... return 42\n' | |
| 2457 ' ...\n' | |
| 2458 ' >>> f()\n' | |
| 2459 ' 42\n' | |
| 2460 '\n' | |
| 2461 'The exception information is not available to the program ' | |
| 2462 'during\n' | |
| 2463 'execution of the "finally" clause.\n' | |
| 2464 '\n' | |
| 2465 'When a "return", "break" or "continue" statement is executed in ' | |
| 2466 'the\n' | |
| 2467 '"try" suite of a "try"…"finally" statement, the "finally" clause ' | |
| 2468 'is\n' | |
| 2469 'also executed ‘on the way out.’\n' | |
| 2470 '\n' | |
| 2471 'The return value of a function is determined by the last ' | |
| 2472 '"return"\n' | |
| 2473 'statement executed. Since the "finally" clause always executes, ' | |
| 2474 'a\n' | |
| 2475 '"return" statement executed in the "finally" clause will always ' | |
| 2476 'be the\n' | |
| 2477 'last one executed:\n' | |
| 2478 '\n' | |
| 2479 ' >>> def foo():\n' | |
| 2480 ' ... try:\n' | |
| 2481 " ... return 'try'\n" | |
| 2482 ' ... finally:\n' | |
| 2483 " ... return 'finally'\n" | |
| 2484 ' ...\n' | |
| 2485 ' >>> foo()\n' | |
| 2486 " 'finally'\n" | |
| 2487 '\n' | |
| 2488 'Additional information on exceptions can be found in section\n' | |
| 2489 'Exceptions, and information on using the "raise" statement to ' | |
| 2490 'generate\n' | |
| 2491 'exceptions may be found in section The raise statement.\n' | |
| 2492 '\n' | |
| 2493 'Changed in version 3.8: Prior to Python 3.8, a "continue" ' | |
| 2494 'statement\n' | |
| 2495 'was illegal in the "finally" clause due to a problem with the\n' | |
| 2496 'implementation.\n' | |
| 2497 '\n' | |
| 2498 '\n' | |
| 2499 'The "with" statement\n' | |
| 2500 '====================\n' | |
| 2501 '\n' | |
| 2502 'The "with" statement is used to wrap the execution of a block ' | |
| 2503 'with\n' | |
| 2504 'methods defined by a context manager (see section With ' | |
| 2505 'Statement\n' | |
| 2506 'Context Managers). This allows common "try"…"except"…"finally" ' | |
| 2507 'usage\n' | |
| 2508 'patterns to be encapsulated for convenient reuse.\n' | |
| 2509 '\n' | |
| 2510 ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' | |
| 2511 ' with_item ::= expression ["as" target]\n' | |
| 2512 '\n' | |
| 2513 'The execution of the "with" statement with one “item” proceeds ' | |
| 2514 'as\n' | |
| 2515 'follows:\n' | |
| 2516 '\n' | |
| 2517 '1. The context expression (the expression given in the ' | |
| 2518 '"with_item")\n' | |
| 2519 ' is evaluated to obtain a context manager.\n' | |
| 2520 '\n' | |
| 2521 '2. The context manager’s "__exit__()" is loaded for later use.\n' | |
| 2522 '\n' | |
| 2523 '3. The context manager’s "__enter__()" method is invoked.\n' | |
| 2524 '\n' | |
| 2525 '4. If a target was included in the "with" statement, the return\n' | |
| 2526 ' value from "__enter__()" is assigned to it.\n' | |
| 2527 '\n' | |
| 2528 ' Note: The "with" statement guarantees that if the ' | |
| 2529 '"__enter__()"\n' | |
| 2530 ' method returns without an error, then "__exit__()" will ' | |
| 2531 'always be\n' | |
| 2532 ' called. Thus, if an error occurs during the assignment to ' | |
| 2533 'the\n' | |
| 2534 ' target list, it will be treated the same as an error ' | |
| 2535 'occurring\n' | |
| 2536 ' within the suite would be. See step 6 below.\n' | |
| 2537 '\n' | |
| 2538 '5. The suite is executed.\n' | |
| 2539 '\n' | |
| 2540 '6. The context manager’s "__exit__()" method is invoked. If an\n' | |
| 2541 ' exception caused the suite to be exited, its type, value, ' | |
| 2542 'and\n' | |
| 2543 ' traceback are passed as arguments to "__exit__()". Otherwise, ' | |
| 2544 'three\n' | |
| 2545 ' "None" arguments are supplied.\n' | |
| 2546 '\n' | |
| 2547 ' If the suite was exited due to an exception, and the return ' | |
| 2548 'value\n' | |
| 2549 ' from the "__exit__()" method was false, the exception is ' | |
| 2550 'reraised.\n' | |
| 2551 ' If the return value was true, the exception is suppressed, ' | |
| 2552 'and\n' | |
| 2553 ' execution continues with the statement following the "with"\n' | |
| 2554 ' statement.\n' | |
| 2555 '\n' | |
| 2556 ' If the suite was exited for any reason other than an ' | |
| 2557 'exception, the\n' | |
| 2558 ' return value from "__exit__()" is ignored, and execution ' | |
| 2559 'proceeds\n' | |
| 2560 ' at the normal location for the kind of exit that was taken.\n' | |
| 2561 '\n' | |
| 2562 'With more than one item, the context managers are processed as ' | |
| 2563 'if\n' | |
| 2564 'multiple "with" statements were nested:\n' | |
| 2565 '\n' | |
| 2566 ' with A() as a, B() as b:\n' | |
| 2567 ' suite\n' | |
| 2568 '\n' | |
| 2569 'is equivalent to\n' | |
| 2570 '\n' | |
| 2571 ' with A() as a:\n' | |
| 2572 ' with B() as b:\n' | |
| 2573 ' suite\n' | |
| 2574 '\n' | |
| 2575 'Changed in version 3.1: Support for multiple context ' | |
| 2576 'expressions.\n' | |
| 2577 '\n' | |
| 2578 'See also:\n' | |
| 2579 '\n' | |
| 2580 ' **PEP 343** - The “with” statement\n' | |
| 2581 ' The specification, background, and examples for the Python ' | |
| 2582 '"with"\n' | |
| 2583 ' statement.\n' | |
| 2584 '\n' | |
| 2585 '\n' | |
| 2586 'Function definitions\n' | |
| 2587 '====================\n' | |
| 2588 '\n' | |
| 2589 'A function definition defines a user-defined function object ' | |
| 2590 '(see\n' | |
| 2591 'section The standard type hierarchy):\n' | |
| 2592 '\n' | |
| 2593 ' funcdef ::= [decorators] "def" funcname "(" ' | |
| 2594 '[parameter_list] ")"\n' | |
| 2595 ' ["->" expression] ":" suite\n' | |
| 2596 ' decorators ::= decorator+\n' | |
| 2597 ' decorator ::= "@" dotted_name ["(" ' | |
| 2598 '[argument_list [","]] ")"] NEWLINE\n' | |
| 2599 ' dotted_name ::= identifier ("." identifier)*\n' | |
| 2600 ' parameter_list ::= defparameter ("," ' | |
| 2601 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n' | |
| 2602 ' | parameter_list_no_posonly\n' | |
| 2603 ' parameter_list_no_posonly ::= defparameter ("," ' | |
| 2604 'defparameter)* ["," [parameter_list_starargs]]\n' | |
| 2605 ' | parameter_list_starargs\n' | |
| 2606 ' parameter_list_starargs ::= "*" [parameter] ("," ' | |
| 2607 'defparameter)* ["," ["**" parameter [","]]]\n' | |
| 2608 ' | "**" parameter [","]\n' | |
| 2609 ' parameter ::= identifier [":" expression]\n' | |
| 2610 ' defparameter ::= parameter ["=" expression]\n' | |
| 2611 ' funcname ::= identifier\n' | |
| 2612 '\n' | |
| 2613 'A function definition is an executable statement. Its execution ' | |
| 2614 'binds\n' | |
| 2615 'the function name in the current local namespace to a function ' | |
| 2616 'object\n' | |
| 2617 '(a wrapper around the executable code for the function). This\n' | |
| 2618 'function object contains a reference to the current global ' | |
| 2619 'namespace\n' | |
| 2620 'as the global namespace to be used when the function is called.\n' | |
| 2621 '\n' | |
| 2622 'The function definition does not execute the function body; this ' | |
| 2623 'gets\n' | |
| 2624 'executed only when the function is called. [2]\n' | |
| 2625 '\n' | |
| 2626 'A function definition may be wrapped by one or more *decorator*\n' | |
| 2627 'expressions. Decorator expressions are evaluated when the ' | |
| 2628 'function is\n' | |
| 2629 'defined, in the scope that contains the function definition. ' | |
| 2630 'The\n' | |
| 2631 'result must be a callable, which is invoked with the function ' | |
| 2632 'object\n' | |
| 2633 'as the only argument. The returned value is bound to the ' | |
| 2634 'function name\n' | |
| 2635 'instead of the function object. Multiple decorators are applied ' | |
| 2636 'in\n' | |
| 2637 'nested fashion. For example, the following code\n' | |
| 2638 '\n' | |
| 2639 ' @f1(arg)\n' | |
| 2640 ' @f2\n' | |
| 2641 ' def func(): pass\n' | |
| 2642 '\n' | |
| 2643 'is roughly equivalent to\n' | |
| 2644 '\n' | |
| 2645 ' def func(): pass\n' | |
| 2646 ' func = f1(arg)(f2(func))\n' | |
| 2647 '\n' | |
| 2648 'except that the original function is not temporarily bound to ' | |
| 2649 'the name\n' | |
| 2650 '"func".\n' | |
| 2651 '\n' | |
| 2652 'When one or more *parameters* have the form *parameter* "="\n' | |
| 2653 '*expression*, the function is said to have “default parameter ' | |
| 2654 'values.”\n' | |
| 2655 'For a parameter with a default value, the corresponding ' | |
| 2656 '*argument* may\n' | |
| 2657 'be omitted from a call, in which case the parameter’s default ' | |
| 2658 'value is\n' | |
| 2659 'substituted. If a parameter has a default value, all following\n' | |
| 2660 'parameters up until the “"*"” must also have a default value — ' | |
| 2661 'this is\n' | |
| 2662 'a syntactic restriction that is not expressed by the grammar.\n' | |
| 2663 '\n' | |
| 2664 '**Default parameter values are evaluated from left to right when ' | |
| 2665 'the\n' | |
| 2666 'function definition is executed.** This means that the ' | |
| 2667 'expression is\n' | |
| 2668 'evaluated once, when the function is defined, and that the same ' | |
| 2669 '“pre-\n' | |
| 2670 'computed” value is used for each call. This is especially ' | |
| 2671 'important\n' | |
| 2672 'to understand when a default parameter is a mutable object, such ' | |
| 2673 'as a\n' | |
| 2674 'list or a dictionary: if the function modifies the object (e.g. ' | |
| 2675 'by\n' | |
| 2676 'appending an item to a list), the default value is in effect ' | |
| 2677 'modified.\n' | |
| 2678 'This is generally not what was intended. A way around this is ' | |
| 2679 'to use\n' | |
| 2680 '"None" as the default, and explicitly test for it in the body of ' | |
| 2681 'the\n' | |
| 2682 'function, e.g.:\n' | |
| 2683 '\n' | |
| 2684 ' def whats_on_the_telly(penguin=None):\n' | |
| 2685 ' if penguin is None:\n' | |
| 2686 ' penguin = []\n' | |
| 2687 ' penguin.append("property of the zoo")\n' | |
| 2688 ' return penguin\n' | |
| 2689 '\n' | |
| 2690 'Function call semantics are described in more detail in section ' | |
| 2691 'Calls.\n' | |
| 2692 'A function call always assigns values to all parameters ' | |
| 2693 'mentioned in\n' | |
| 2694 'the parameter list, either from position arguments, from ' | |
| 2695 'keyword\n' | |
| 2696 'arguments, or from default values. If the form “"*identifier"” ' | |
| 2697 'is\n' | |
| 2698 'present, it is initialized to a tuple receiving any excess ' | |
| 2699 'positional\n' | |
| 2700 'parameters, defaulting to the empty tuple. If the form\n' | |
| 2701 '“"**identifier"” is present, it is initialized to a new ordered\n' | |
| 2702 'mapping receiving any excess keyword arguments, defaulting to a ' | |
| 2703 'new\n' | |
| 2704 'empty mapping of the same type. Parameters after “"*"” or\n' | |
| 2705 '“"*identifier"” are keyword-only parameters and may only be ' | |
| 2706 'passed\n' | |
| 2707 'used keyword arguments.\n' | |
| 2708 '\n' | |
| 2709 'Parameters may have an *annotation* of the form “": ' | |
| 2710 'expression"”\n' | |
| 2711 'following the parameter name. Any parameter may have an ' | |
| 2712 'annotation,\n' | |
| 2713 'even those of the form "*identifier" or "**identifier". ' | |
| 2714 'Functions may\n' | |
| 2715 'have “return” annotation of the form “"-> expression"” after ' | |
| 2716 'the\n' | |
| 2717 'parameter list. These annotations can be any valid Python ' | |
| 2718 'expression.\n' | |
| 2719 'The presence of annotations does not change the semantics of a\n' | |
| 2720 'function. The annotation values are available as values of a\n' | |
| 2721 'dictionary keyed by the parameters’ names in the ' | |
| 2722 '"__annotations__"\n' | |
| 2723 'attribute of the function object. If the "annotations" import ' | |
| 2724 'from\n' | |
| 2725 '"__future__" is used, annotations are preserved as strings at ' | |
| 2726 'runtime\n' | |
| 2727 'which enables postponed evaluation. Otherwise, they are ' | |
| 2728 'evaluated\n' | |
| 2729 'when the function definition is executed. In this case ' | |
| 2730 'annotations\n' | |
| 2731 'may be evaluated in a different order than they appear in the ' | |
| 2732 'source\n' | |
| 2733 'code.\n' | |
| 2734 '\n' | |
| 2735 'It is also possible to create anonymous functions (functions not ' | |
| 2736 'bound\n' | |
| 2737 'to a name), for immediate use in expressions. This uses lambda\n' | |
| 2738 'expressions, described in section Lambdas. Note that the ' | |
| 2739 'lambda\n' | |
| 2740 'expression is merely a shorthand for a simplified function ' | |
| 2741 'definition;\n' | |
| 2742 'a function defined in a “"def"” statement can be passed around ' | |
| 2743 'or\n' | |
| 2744 'assigned to another name just like a function defined by a ' | |
| 2745 'lambda\n' | |
| 2746 'expression. The “"def"” form is actually more powerful since ' | |
| 2747 'it\n' | |
| 2748 'allows the execution of multiple statements and annotations.\n' | |
| 2749 '\n' | |
| 2750 '**Programmer’s note:** Functions are first-class objects. A ' | |
| 2751 '“"def"”\n' | |
| 2752 'statement executed inside a function definition defines a local\n' | |
| 2753 'function that can be returned or passed around. Free variables ' | |
| 2754 'used\n' | |
| 2755 'in the nested function can access the local variables of the ' | |
| 2756 'function\n' | |
| 2757 'containing the def. See section Naming and binding for ' | |
| 2758 'details.\n' | |
| 2759 '\n' | |
| 2760 'See also:\n' | |
| 2761 '\n' | |
| 2762 ' **PEP 3107** - Function Annotations\n' | |
| 2763 ' The original specification for function annotations.\n' | |
| 2764 '\n' | |
| 2765 ' **PEP 484** - Type Hints\n' | |
| 2766 ' Definition of a standard meaning for annotations: type ' | |
| 2767 'hints.\n' | |
| 2768 '\n' | |
| 2769 ' **PEP 526** - Syntax for Variable Annotations\n' | |
| 2770 ' Ability to type hint variable declarations, including ' | |
| 2771 'class\n' | |
| 2772 ' variables and instance variables\n' | |
| 2773 '\n' | |
| 2774 ' **PEP 563** - Postponed Evaluation of Annotations\n' | |
| 2775 ' Support for forward references within annotations by ' | |
| 2776 'preserving\n' | |
| 2777 ' annotations in a string form at runtime instead of eager\n' | |
| 2778 ' evaluation.\n' | |
| 2779 '\n' | |
| 2780 '\n' | |
| 2781 'Class definitions\n' | |
| 2782 '=================\n' | |
| 2783 '\n' | |
| 2784 'A class definition defines a class object (see section The ' | |
| 2785 'standard\n' | |
| 2786 'type hierarchy):\n' | |
| 2787 '\n' | |
| 2788 ' classdef ::= [decorators] "class" classname [inheritance] ' | |
| 2789 '":" suite\n' | |
| 2790 ' inheritance ::= "(" [argument_list] ")"\n' | |
| 2791 ' classname ::= identifier\n' | |
| 2792 '\n' | |
| 2793 'A class definition is an executable statement. The inheritance ' | |
| 2794 'list\n' | |
| 2795 'usually gives a list of base classes (see Metaclasses for more\n' | |
| 2796 'advanced uses), so each item in the list should evaluate to a ' | |
| 2797 'class\n' | |
| 2798 'object which allows subclassing. Classes without an inheritance ' | |
| 2799 'list\n' | |
| 2800 'inherit, by default, from the base class "object"; hence,\n' | |
| 2801 '\n' | |
| 2802 ' class Foo:\n' | |
| 2803 ' pass\n' | |
| 2804 '\n' | |
| 2805 'is equivalent to\n' | |
| 2806 '\n' | |
| 2807 ' class Foo(object):\n' | |
| 2808 ' pass\n' | |
| 2809 '\n' | |
| 2810 'The class’s suite is then executed in a new execution frame ' | |
| 2811 '(see\n' | |
| 2812 'Naming and binding), using a newly created local namespace and ' | |
| 2813 'the\n' | |
| 2814 'original global namespace. (Usually, the suite contains mostly\n' | |
| 2815 'function definitions.) When the class’s suite finishes ' | |
| 2816 'execution, its\n' | |
| 2817 'execution frame is discarded but its local namespace is saved. ' | |
| 2818 '[3] A\n' | |
| 2819 'class object is then created using the inheritance list for the ' | |
| 2820 'base\n' | |
| 2821 'classes and the saved local namespace for the attribute ' | |
| 2822 'dictionary.\n' | |
| 2823 'The class name is bound to this class object in the original ' | |
| 2824 'local\n' | |
| 2825 'namespace.\n' | |
| 2826 '\n' | |
| 2827 'The order in which attributes are defined in the class body is\n' | |
| 2828 'preserved in the new class’s "__dict__". Note that this is ' | |
| 2829 'reliable\n' | |
| 2830 'only right after the class is created and only for classes that ' | |
| 2831 'were\n' | |
| 2832 'defined using the definition syntax.\n' | |
| 2833 '\n' | |
| 2834 'Class creation can be customized heavily using metaclasses.\n' | |
| 2835 '\n' | |
| 2836 'Classes can also be decorated: just like when decorating ' | |
| 2837 'functions,\n' | |
| 2838 '\n' | |
| 2839 ' @f1(arg)\n' | |
| 2840 ' @f2\n' | |
| 2841 ' class Foo: pass\n' | |
| 2842 '\n' | |
| 2843 'is roughly equivalent to\n' | |
| 2844 '\n' | |
| 2845 ' class Foo: pass\n' | |
| 2846 ' Foo = f1(arg)(f2(Foo))\n' | |
| 2847 '\n' | |
| 2848 'The evaluation rules for the decorator expressions are the same ' | |
| 2849 'as for\n' | |
| 2850 'function decorators. The result is then bound to the class ' | |
| 2851 'name.\n' | |
| 2852 '\n' | |
| 2853 '**Programmer’s note:** Variables defined in the class definition ' | |
| 2854 'are\n' | |
| 2855 'class attributes; they are shared by instances. Instance ' | |
| 2856 'attributes\n' | |
| 2857 'can be set in a method with "self.name = value". Both class ' | |
| 2858 'and\n' | |
| 2859 'instance attributes are accessible through the notation ' | |
| 2860 '“"self.name"”,\n' | |
| 2861 'and an instance attribute hides a class attribute with the same ' | |
| 2862 'name\n' | |
| 2863 'when accessed in this way. Class attributes can be used as ' | |
| 2864 'defaults\n' | |
| 2865 'for instance attributes, but using mutable values there can lead ' | |
| 2866 'to\n' | |
| 2867 'unexpected results. Descriptors can be used to create instance\n' | |
| 2868 'variables with different implementation details.\n' | |
| 2869 '\n' | |
| 2870 'See also:\n' | |
| 2871 '\n' | |
| 2872 ' **PEP 3115** - Metaclasses in Python 3000\n' | |
| 2873 ' The proposal that changed the declaration of metaclasses to ' | |
| 2874 'the\n' | |
| 2875 ' current syntax, and the semantics for how classes with\n' | |
| 2876 ' metaclasses are constructed.\n' | |
| 2877 '\n' | |
| 2878 ' **PEP 3129** - Class Decorators\n' | |
| 2879 ' The proposal that added class decorators. Function and ' | |
| 2880 'method\n' | |
| 2881 ' decorators were introduced in **PEP 318**.\n' | |
| 2882 '\n' | |
| 2883 '\n' | |
| 2884 'Coroutines\n' | |
| 2885 '==========\n' | |
| 2886 '\n' | |
| 2887 'New in version 3.5.\n' | |
| 2888 '\n' | |
| 2889 '\n' | |
| 2890 'Coroutine function definition\n' | |
| 2891 '-----------------------------\n' | |
| 2892 '\n' | |
| 2893 ' async_funcdef ::= [decorators] "async" "def" funcname "(" ' | |
| 2894 '[parameter_list] ")"\n' | |
| 2895 ' ["->" expression] ":" suite\n' | |
| 2896 '\n' | |
| 2897 'Execution of Python coroutines can be suspended and resumed at ' | |
| 2898 'many\n' | |
| 2899 'points (see *coroutine*). Inside the body of a coroutine ' | |
| 2900 'function,\n' | |
| 2901 '"await" and "async" identifiers become reserved keywords; ' | |
| 2902 '"await"\n' | |
| 2903 'expressions, "async for" and "async with" can only be used in\n' | |
| 2904 'coroutine function bodies.\n' | |
| 2905 '\n' | |
| 2906 'Functions defined with "async def" syntax are always coroutine\n' | |
| 2907 'functions, even if they do not contain "await" or "async" ' | |
| 2908 'keywords.\n' | |
| 2909 '\n' | |
| 2910 'It is a "SyntaxError" to use a "yield from" expression inside ' | |
| 2911 'the body\n' | |
| 2912 'of a coroutine function.\n' | |
| 2913 '\n' | |
| 2914 'An example of a coroutine function:\n' | |
| 2915 '\n' | |
| 2916 ' async def func(param1, param2):\n' | |
| 2917 ' do_stuff()\n' | |
| 2918 ' await some_coroutine()\n' | |
| 2919 '\n' | |
| 2920 '\n' | |
| 2921 'The "async for" statement\n' | |
| 2922 '-------------------------\n' | |
| 2923 '\n' | |
| 2924 ' async_for_stmt ::= "async" for_stmt\n' | |
| 2925 '\n' | |
| 2926 'An *asynchronous iterable* is able to call asynchronous code in ' | |
| 2927 'its\n' | |
| 2928 '*iter* implementation, and *asynchronous iterator* can call\n' | |
| 2929 'asynchronous code in its *next* method.\n' | |
| 2930 '\n' | |
| 2931 'The "async for" statement allows convenient iteration over\n' | |
| 2932 'asynchronous iterators.\n' | |
| 2933 '\n' | |
| 2934 'The following code:\n' | |
| 2935 '\n' | |
| 2936 ' async for TARGET in ITER:\n' | |
| 2937 ' BLOCK\n' | |
| 2938 ' else:\n' | |
| 2939 ' BLOCK2\n' | |
| 2940 '\n' | |
| 2941 'Is semantically equivalent to:\n' | |
| 2942 '\n' | |
| 2943 ' iter = (ITER)\n' | |
| 2944 ' iter = type(iter).__aiter__(iter)\n' | |
| 2945 ' running = True\n' | |
| 2946 ' while running:\n' | |
| 2947 ' try:\n' | |
| 2948 ' TARGET = await type(iter).__anext__(iter)\n' | |
| 2949 ' except StopAsyncIteration:\n' | |
| 2950 ' running = False\n' | |
| 2951 ' else:\n' | |
| 2952 ' BLOCK\n' | |
| 2953 ' else:\n' | |
| 2954 ' BLOCK2\n' | |
| 2955 '\n' | |
| 2956 'See also "__aiter__()" and "__anext__()" for details.\n' | |
| 2957 '\n' | |
| 2958 'It is a "SyntaxError" to use an "async for" statement outside ' | |
| 2959 'the body\n' | |
| 2960 'of a coroutine function.\n' | |
| 2961 '\n' | |
| 2962 '\n' | |
| 2963 'The "async with" statement\n' | |
| 2964 '--------------------------\n' | |
| 2965 '\n' | |
| 2966 ' async_with_stmt ::= "async" with_stmt\n' | |
| 2967 '\n' | |
| 2968 'An *asynchronous context manager* is a *context manager* that is ' | |
| 2969 'able\n' | |
| 2970 'to suspend execution in its *enter* and *exit* methods.\n' | |
| 2971 '\n' | |
| 2972 'The following code:\n' | |
| 2973 '\n' | |
| 2974 ' async with EXPR as VAR:\n' | |
| 2975 ' BLOCK\n' | |
| 2976 '\n' | |
| 2977 'Is semantically equivalent to:\n' | |
| 2978 '\n' | |
| 2979 ' mgr = (EXPR)\n' | |
| 2980 ' aexit = type(mgr).__aexit__\n' | |
| 2981 ' aenter = type(mgr).__aenter__(mgr)\n' | |
| 2982 '\n' | |
| 2983 ' VAR = await aenter\n' | |
| 2984 ' try:\n' | |
| 2985 ' BLOCK\n' | |
| 2986 ' except:\n' | |
| 2987 ' if not await aexit(mgr, *sys.exc_info()):\n' | |
| 2988 ' raise\n' | |
| 2989 ' else:\n' | |
| 2990 ' await aexit(mgr, None, None, None)\n' | |
| 2991 '\n' | |
| 2992 'See also "__aenter__()" and "__aexit__()" for details.\n' | |
| 2993 '\n' | |
| 2994 'It is a "SyntaxError" to use an "async with" statement outside ' | |
| 2995 'the\n' | |
| 2996 'body of a coroutine function.\n' | |
| 2997 '\n' | |
| 2998 'See also:\n' | |
| 2999 '\n' | |
| 3000 ' **PEP 492** - Coroutines with async and await syntax\n' | |
| 3001 ' The proposal that made coroutines a proper standalone ' | |
| 3002 'concept in\n' | |
| 3003 ' Python, and added supporting syntax.\n' | |
| 3004 '\n' | |
| 3005 '-[ Footnotes ]-\n' | |
| 3006 '\n' | |
| 3007 '[1] The exception is propagated to the invocation stack unless\n' | |
| 3008 ' there is a "finally" clause which happens to raise another\n' | |
| 3009 ' exception. That new exception causes the old one to be ' | |
| 3010 'lost.\n' | |
| 3011 '\n' | |
| 3012 '[2] A string literal appearing as the first statement in the\n' | |
| 3013 ' function body is transformed into the function’s "__doc__"\n' | |
| 3014 ' attribute and therefore the function’s *docstring*.\n' | |
| 3015 '\n' | |
| 3016 '[3] A string literal appearing as the first statement in the ' | |
| 3017 'class\n' | |
| 3018 ' body is transformed into the namespace’s "__doc__" item and\n' | |
| 3019 ' therefore the class’s *docstring*.\n', | |
| 3020 'context-managers': 'With Statement Context Managers\n' | |
| 3021 '*******************************\n' | |
| 3022 '\n' | |
| 3023 'A *context manager* is an object that defines the ' | |
| 3024 'runtime context to\n' | |
| 3025 'be established when executing a "with" statement. The ' | |
| 3026 'context manager\n' | |
| 3027 'handles the entry into, and the exit from, the desired ' | |
| 3028 'runtime context\n' | |
| 3029 'for the execution of the block of code. Context ' | |
| 3030 'managers are normally\n' | |
| 3031 'invoked using the "with" statement (described in section ' | |
| 3032 'The with\n' | |
| 3033 'statement), but can also be used by directly invoking ' | |
| 3034 'their methods.\n' | |
| 3035 '\n' | |
| 3036 'Typical uses of context managers include saving and ' | |
| 3037 'restoring various\n' | |
| 3038 'kinds of global state, locking and unlocking resources, ' | |
| 3039 'closing opened\n' | |
| 3040 'files, etc.\n' | |
| 3041 '\n' | |
| 3042 'For more information on context managers, see Context ' | |
| 3043 'Manager Types.\n' | |
| 3044 '\n' | |
| 3045 'object.__enter__(self)\n' | |
| 3046 '\n' | |
| 3047 ' Enter the runtime context related to this object. The ' | |
| 3048 '"with"\n' | |
| 3049 ' statement will bind this method’s return value to the ' | |
| 3050 'target(s)\n' | |
| 3051 ' specified in the "as" clause of the statement, if ' | |
| 3052 'any.\n' | |
| 3053 '\n' | |
| 3054 'object.__exit__(self, exc_type, exc_value, traceback)\n' | |
| 3055 '\n' | |
| 3056 ' Exit the runtime context related to this object. The ' | |
| 3057 'parameters\n' | |
| 3058 ' describe the exception that caused the context to be ' | |
| 3059 'exited. If the\n' | |
| 3060 ' context was exited without an exception, all three ' | |
| 3061 'arguments will\n' | |
| 3062 ' be "None".\n' | |
| 3063 '\n' | |
| 3064 ' If an exception is supplied, and the method wishes to ' | |
| 3065 'suppress the\n' | |
| 3066 ' exception (i.e., prevent it from being propagated), ' | |
| 3067 'it should\n' | |
| 3068 ' return a true value. Otherwise, the exception will be ' | |
| 3069 'processed\n' | |
| 3070 ' normally upon exit from this method.\n' | |
| 3071 '\n' | |
| 3072 ' Note that "__exit__()" methods should not reraise the ' | |
| 3073 'passed-in\n' | |
| 3074 ' exception; this is the caller’s responsibility.\n' | |
| 3075 '\n' | |
| 3076 'See also:\n' | |
| 3077 '\n' | |
| 3078 ' **PEP 343** - The “with” statement\n' | |
| 3079 ' The specification, background, and examples for the ' | |
| 3080 'Python "with"\n' | |
| 3081 ' statement.\n', | |
| 3082 'continue': 'The "continue" statement\n' | |
| 3083 '************************\n' | |
| 3084 '\n' | |
| 3085 ' continue_stmt ::= "continue"\n' | |
| 3086 '\n' | |
| 3087 '"continue" may only occur syntactically nested in a "for" or ' | |
| 3088 '"while"\n' | |
| 3089 'loop, but not nested in a function or class definition within ' | |
| 3090 'that\n' | |
| 3091 'loop. It continues with the next cycle of the nearest enclosing ' | |
| 3092 'loop.\n' | |
| 3093 '\n' | |
| 3094 'When "continue" passes control out of a "try" statement with a\n' | |
| 3095 '"finally" clause, that "finally" clause is executed before ' | |
| 3096 'really\n' | |
| 3097 'starting the next loop cycle.\n', | |
| 3098 'conversions': 'Arithmetic conversions\n' | |
| 3099 '**********************\n' | |
| 3100 '\n' | |
| 3101 'When a description of an arithmetic operator below uses the ' | |
| 3102 'phrase\n' | |
| 3103 '“the numeric arguments are converted to a common type,” this ' | |
| 3104 'means\n' | |
| 3105 'that the operator implementation for built-in types works as ' | |
| 3106 'follows:\n' | |
| 3107 '\n' | |
| 3108 '* If either argument is a complex number, the other is ' | |
| 3109 'converted to\n' | |
| 3110 ' complex;\n' | |
| 3111 '\n' | |
| 3112 '* otherwise, if either argument is a floating point number, ' | |
| 3113 'the\n' | |
| 3114 ' other is converted to floating point;\n' | |
| 3115 '\n' | |
| 3116 '* otherwise, both must be integers and no conversion is ' | |
| 3117 'necessary.\n' | |
| 3118 '\n' | |
| 3119 'Some additional rules apply for certain operators (e.g., a ' | |
| 3120 'string as a\n' | |
| 3121 'left argument to the ‘%’ operator). Extensions must define ' | |
| 3122 'their own\n' | |
| 3123 'conversion behavior.\n', | |
| 3124 'customization': 'Basic customization\n' | |
| 3125 '*******************\n' | |
| 3126 '\n' | |
| 3127 'object.__new__(cls[, ...])\n' | |
| 3128 '\n' | |
| 3129 ' Called to create a new instance of class *cls*. ' | |
| 3130 '"__new__()" is a\n' | |
| 3131 ' static method (special-cased so you need not declare it ' | |
| 3132 'as such)\n' | |
| 3133 ' that takes the class of which an instance was requested ' | |
| 3134 'as its\n' | |
| 3135 ' first argument. The remaining arguments are those ' | |
| 3136 'passed to the\n' | |
| 3137 ' object constructor expression (the call to the class). ' | |
| 3138 'The return\n' | |
| 3139 ' value of "__new__()" should be the new object instance ' | |
| 3140 '(usually an\n' | |
| 3141 ' instance of *cls*).\n' | |
| 3142 '\n' | |
| 3143 ' Typical implementations create a new instance of the ' | |
| 3144 'class by\n' | |
| 3145 ' invoking the superclass’s "__new__()" method using\n' | |
| 3146 ' "super().__new__(cls[, ...])" with appropriate arguments ' | |
| 3147 'and then\n' | |
| 3148 ' modifying the newly-created instance as necessary before ' | |
| 3149 'returning\n' | |
| 3150 ' it.\n' | |
| 3151 '\n' | |
| 3152 ' If "__new__()" is invoked during object construction and ' | |
| 3153 'it returns\n' | |
| 3154 ' an instance or subclass of *cls*, then the new ' | |
| 3155 'instance’s\n' | |
| 3156 ' "__init__()" method will be invoked like ' | |
| 3157 '"__init__(self[, ...])",\n' | |
| 3158 ' where *self* is the new instance and the remaining ' | |
| 3159 'arguments are\n' | |
| 3160 ' the same as were passed to the object constructor.\n' | |
| 3161 '\n' | |
| 3162 ' If "__new__()" does not return an instance of *cls*, ' | |
| 3163 'then the new\n' | |
| 3164 ' instance’s "__init__()" method will not be invoked.\n' | |
| 3165 '\n' | |
| 3166 ' "__new__()" is intended mainly to allow subclasses of ' | |
| 3167 'immutable\n' | |
| 3168 ' types (like int, str, or tuple) to customize instance ' | |
| 3169 'creation. It\n' | |
| 3170 ' is also commonly overridden in custom metaclasses in ' | |
| 3171 'order to\n' | |
| 3172 ' customize class creation.\n' | |
| 3173 '\n' | |
| 3174 'object.__init__(self[, ...])\n' | |
| 3175 '\n' | |
| 3176 ' Called after the instance has been created (by ' | |
| 3177 '"__new__()"), but\n' | |
| 3178 ' before it is returned to the caller. The arguments are ' | |
| 3179 'those\n' | |
| 3180 ' passed to the class constructor expression. If a base ' | |
| 3181 'class has an\n' | |
| 3182 ' "__init__()" method, the derived class’s "__init__()" ' | |
| 3183 'method, if\n' | |
| 3184 ' any, must explicitly call it to ensure proper ' | |
| 3185 'initialization of the\n' | |
| 3186 ' base class part of the instance; for example:\n' | |
| 3187 ' "super().__init__([args...])".\n' | |
| 3188 '\n' | |
| 3189 ' Because "__new__()" and "__init__()" work together in ' | |
| 3190 'constructing\n' | |
| 3191 ' objects ("__new__()" to create it, and "__init__()" to ' | |
| 3192 'customize\n' | |
| 3193 ' it), no non-"None" value may be returned by ' | |
| 3194 '"__init__()"; doing so\n' | |
| 3195 ' will cause a "TypeError" to be raised at runtime.\n' | |
| 3196 '\n' | |
| 3197 'object.__del__(self)\n' | |
| 3198 '\n' | |
| 3199 ' Called when the instance is about to be destroyed. This ' | |
| 3200 'is also\n' | |
| 3201 ' called a finalizer or (improperly) a destructor. If a ' | |
| 3202 'base class\n' | |
| 3203 ' has a "__del__()" method, the derived class’s ' | |
| 3204 '"__del__()" method,\n' | |
| 3205 ' if any, must explicitly call it to ensure proper ' | |
| 3206 'deletion of the\n' | |
| 3207 ' base class part of the instance.\n' | |
| 3208 '\n' | |
| 3209 ' It is possible (though not recommended!) for the ' | |
| 3210 '"__del__()" method\n' | |
| 3211 ' to postpone destruction of the instance by creating a ' | |
| 3212 'new reference\n' | |
| 3213 ' to it. This is called object *resurrection*. It is\n' | |
| 3214 ' implementation-dependent whether "__del__()" is called a ' | |
| 3215 'second\n' | |
| 3216 ' time when a resurrected object is about to be destroyed; ' | |
| 3217 'the\n' | |
| 3218 ' current *CPython* implementation only calls it once.\n' | |
| 3219 '\n' | |
| 3220 ' It is not guaranteed that "__del__()" methods are called ' | |
| 3221 'for\n' | |
| 3222 ' objects that still exist when the interpreter exits.\n' | |
| 3223 '\n' | |
| 3224 ' Note: "del x" doesn’t directly call "x.__del__()" — the ' | |
| 3225 'former\n' | |
| 3226 ' decrements the reference count for "x" by one, and the ' | |
| 3227 'latter is\n' | |
| 3228 ' only called when "x"’s reference count reaches zero.\n' | |
| 3229 '\n' | |
| 3230 ' **CPython implementation detail:** It is possible for a ' | |
| 3231 'reference\n' | |
| 3232 ' cycle to prevent the reference count of an object from ' | |
| 3233 'going to\n' | |
| 3234 ' zero. In this case, the cycle will be later detected ' | |
| 3235 'and deleted\n' | |
| 3236 ' by the *cyclic garbage collector*. A common cause of ' | |
| 3237 'reference\n' | |
| 3238 ' cycles is when an exception has been caught in a local ' | |
| 3239 'variable.\n' | |
| 3240 ' The frame’s locals then reference the exception, which ' | |
| 3241 'references\n' | |
| 3242 ' its own traceback, which references the locals of all ' | |
| 3243 'frames caught\n' | |
| 3244 ' in the traceback.\n' | |
| 3245 '\n' | |
| 3246 ' See also: Documentation for the "gc" module.\n' | |
| 3247 '\n' | |
| 3248 ' Warning: Due to the precarious circumstances under ' | |
| 3249 'which\n' | |
| 3250 ' "__del__()" methods are invoked, exceptions that occur ' | |
| 3251 'during\n' | |
| 3252 ' their execution are ignored, and a warning is printed ' | |
| 3253 'to\n' | |
| 3254 ' "sys.stderr" instead. In particular:\n' | |
| 3255 '\n' | |
| 3256 ' * "__del__()" can be invoked when arbitrary code is ' | |
| 3257 'being\n' | |
| 3258 ' executed, including from any arbitrary thread. If ' | |
| 3259 '"__del__()"\n' | |
| 3260 ' needs to take a lock or invoke any other blocking ' | |
| 3261 'resource, it\n' | |
| 3262 ' may deadlock as the resource may already be taken by ' | |
| 3263 'the code\n' | |
| 3264 ' that gets interrupted to execute "__del__()".\n' | |
| 3265 '\n' | |
| 3266 ' * "__del__()" can be executed during interpreter ' | |
| 3267 'shutdown. As\n' | |
| 3268 ' a consequence, the global variables it needs to ' | |
| 3269 'access\n' | |
| 3270 ' (including other modules) may already have been ' | |
| 3271 'deleted or set\n' | |
| 3272 ' to "None". Python guarantees that globals whose name ' | |
| 3273 'begins\n' | |
| 3274 ' with a single underscore are deleted from their ' | |
| 3275 'module before\n' | |
| 3276 ' other globals are deleted; if no other references to ' | |
| 3277 'such\n' | |
| 3278 ' globals exist, this may help in assuring that ' | |
| 3279 'imported modules\n' | |
| 3280 ' are still available at the time when the "__del__()" ' | |
| 3281 'method is\n' | |
| 3282 ' called.\n' | |
| 3283 '\n' | |
| 3284 'object.__repr__(self)\n' | |
| 3285 '\n' | |
| 3286 ' Called by the "repr()" built-in function to compute the ' | |
| 3287 '“official”\n' | |
| 3288 ' string representation of an object. If at all possible, ' | |
| 3289 'this\n' | |
| 3290 ' should look like a valid Python expression that could be ' | |
| 3291 'used to\n' | |
| 3292 ' recreate an object with the same value (given an ' | |
| 3293 'appropriate\n' | |
| 3294 ' environment). If this is not possible, a string of the ' | |
| 3295 'form\n' | |
| 3296 ' "<...some useful description...>" should be returned. ' | |
| 3297 'The return\n' | |
| 3298 ' value must be a string object. If a class defines ' | |
| 3299 '"__repr__()" but\n' | |
| 3300 ' not "__str__()", then "__repr__()" is also used when an ' | |
| 3301 '“informal”\n' | |
| 3302 ' string representation of instances of that class is ' | |
| 3303 'required.\n' | |
| 3304 '\n' | |
| 3305 ' This is typically used for debugging, so it is important ' | |
| 3306 'that the\n' | |
| 3307 ' representation is information-rich and unambiguous.\n' | |
| 3308 '\n' | |
| 3309 'object.__str__(self)\n' | |
| 3310 '\n' | |
| 3311 ' Called by "str(object)" and the built-in functions ' | |
| 3312 '"format()" and\n' | |
| 3313 ' "print()" to compute the “informal” or nicely printable ' | |
| 3314 'string\n' | |
| 3315 ' representation of an object. The return value must be a ' | |
| 3316 'string\n' | |
| 3317 ' object.\n' | |
| 3318 '\n' | |
| 3319 ' This method differs from "object.__repr__()" in that ' | |
| 3320 'there is no\n' | |
| 3321 ' expectation that "__str__()" return a valid Python ' | |
| 3322 'expression: a\n' | |
| 3323 ' more convenient or concise representation can be used.\n' | |
| 3324 '\n' | |
| 3325 ' The default implementation defined by the built-in type ' | |
| 3326 '"object"\n' | |
| 3327 ' calls "object.__repr__()".\n' | |
| 3328 '\n' | |
| 3329 'object.__bytes__(self)\n' | |
| 3330 '\n' | |
| 3331 ' Called by bytes to compute a byte-string representation ' | |
| 3332 'of an\n' | |
| 3333 ' object. This should return a "bytes" object.\n' | |
| 3334 '\n' | |
| 3335 'object.__format__(self, format_spec)\n' | |
| 3336 '\n' | |
| 3337 ' Called by the "format()" built-in function, and by ' | |
| 3338 'extension,\n' | |
| 3339 ' evaluation of formatted string literals and the ' | |
| 3340 '"str.format()"\n' | |
| 3341 ' method, to produce a “formatted” string representation ' | |
| 3342 'of an\n' | |
| 3343 ' object. The *format_spec* argument is a string that ' | |
| 3344 'contains a\n' | |
| 3345 ' description of the formatting options desired. The ' | |
| 3346 'interpretation\n' | |
| 3347 ' of the *format_spec* argument is up to the type ' | |
| 3348 'implementing\n' | |
| 3349 ' "__format__()", however most classes will either ' | |
| 3350 'delegate\n' | |
| 3351 ' formatting to one of the built-in types, or use a ' | |
| 3352 'similar\n' | |
| 3353 ' formatting option syntax.\n' | |
| 3354 '\n' | |
| 3355 ' See Format Specification Mini-Language for a description ' | |
| 3356 'of the\n' | |
| 3357 ' standard formatting syntax.\n' | |
| 3358 '\n' | |
| 3359 ' The return value must be a string object.\n' | |
| 3360 '\n' | |
| 3361 ' Changed in version 3.4: The __format__ method of ' | |
| 3362 '"object" itself\n' | |
| 3363 ' raises a "TypeError" if passed any non-empty string.\n' | |
| 3364 '\n' | |
| 3365 ' Changed in version 3.7: "object.__format__(x, \'\')" is ' | |
| 3366 'now\n' | |
| 3367 ' equivalent to "str(x)" rather than "format(str(self), ' | |
| 3368 '\'\')".\n' | |
| 3369 '\n' | |
| 3370 'object.__lt__(self, other)\n' | |
| 3371 'object.__le__(self, other)\n' | |
| 3372 'object.__eq__(self, other)\n' | |
| 3373 'object.__ne__(self, other)\n' | |
| 3374 'object.__gt__(self, other)\n' | |
| 3375 'object.__ge__(self, other)\n' | |
| 3376 '\n' | |
| 3377 ' These are the so-called “rich comparison” methods. The\n' | |
| 3378 ' correspondence between operator symbols and method names ' | |
| 3379 'is as\n' | |
| 3380 ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' | |
| 3381 '"x.__le__(y)",\n' | |
| 3382 ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' | |
| 3383 '"x>y" calls\n' | |
| 3384 ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' | |
| 3385 '\n' | |
| 3386 ' A rich comparison method may return the singleton ' | |
| 3387 '"NotImplemented"\n' | |
| 3388 ' if it does not implement the operation for a given pair ' | |
| 3389 'of\n' | |
| 3390 ' arguments. By convention, "False" and "True" are ' | |
| 3391 'returned for a\n' | |
| 3392 ' successful comparison. However, these methods can return ' | |
| 3393 'any value,\n' | |
| 3394 ' so if the comparison operator is used in a Boolean ' | |
| 3395 'context (e.g.,\n' | |
| 3396 ' in the condition of an "if" statement), Python will call ' | |
| 3397 '"bool()"\n' | |
| 3398 ' on the value to determine if the result is true or ' | |
| 3399 'false.\n' | |
| 3400 '\n' | |
| 3401 ' By default, "__ne__()" delegates to "__eq__()" and ' | |
| 3402 'inverts the\n' | |
| 3403 ' result unless it is "NotImplemented". There are no ' | |
| 3404 'other implied\n' | |
| 3405 ' relationships among the comparison operators, for ' | |
| 3406 'example, the\n' | |
| 3407 ' truth of "(x<y or x==y)" does not imply "x<=y". To ' | |
| 3408 'automatically\n' | |
| 3409 ' generate ordering operations from a single root ' | |
| 3410 'operation, see\n' | |
| 3411 ' "functools.total_ordering()".\n' | |
| 3412 '\n' | |
| 3413 ' See the paragraph on "__hash__()" for some important ' | |
| 3414 'notes on\n' | |
| 3415 ' creating *hashable* objects which support custom ' | |
| 3416 'comparison\n' | |
| 3417 ' operations and are usable as dictionary keys.\n' | |
| 3418 '\n' | |
| 3419 ' There are no swapped-argument versions of these methods ' | |
| 3420 '(to be used\n' | |
| 3421 ' when the left argument does not support the operation ' | |
| 3422 'but the right\n' | |
| 3423 ' argument does); rather, "__lt__()" and "__gt__()" are ' | |
| 3424 'each other’s\n' | |
| 3425 ' reflection, "__le__()" and "__ge__()" are each other’s ' | |
| 3426 'reflection,\n' | |
| 3427 ' and "__eq__()" and "__ne__()" are their own reflection. ' | |
| 3428 'If the\n' | |
| 3429 ' operands are of different types, and right operand’s ' | |
| 3430 'type is a\n' | |
| 3431 ' direct or indirect subclass of the left operand’s type, ' | |
| 3432 'the\n' | |
| 3433 ' reflected method of the right operand has priority, ' | |
| 3434 'otherwise the\n' | |
| 3435 ' left operand’s method has priority. Virtual subclassing ' | |
| 3436 'is not\n' | |
| 3437 ' considered.\n' | |
| 3438 '\n' | |
| 3439 'object.__hash__(self)\n' | |
| 3440 '\n' | |
| 3441 ' Called by built-in function "hash()" and for operations ' | |
| 3442 'on members\n' | |
| 3443 ' of hashed collections including "set", "frozenset", and ' | |
| 3444 '"dict".\n' | |
| 3445 ' "__hash__()" should return an integer. The only required ' | |
| 3446 'property\n' | |
| 3447 ' is that objects which compare equal have the same hash ' | |
| 3448 'value; it is\n' | |
| 3449 ' advised to mix together the hash values of the ' | |
| 3450 'components of the\n' | |
| 3451 ' object that also play a part in comparison of objects by ' | |
| 3452 'packing\n' | |
| 3453 ' them into a tuple and hashing the tuple. Example:\n' | |
| 3454 '\n' | |
| 3455 ' def __hash__(self):\n' | |
| 3456 ' return hash((self.name, self.nick, self.color))\n' | |
| 3457 '\n' | |
| 3458 ' Note: "hash()" truncates the value returned from an ' | |
| 3459 'object’s\n' | |
| 3460 ' custom "__hash__()" method to the size of a ' | |
| 3461 '"Py_ssize_t". This\n' | |
| 3462 ' is typically 8 bytes on 64-bit builds and 4 bytes on ' | |
| 3463 '32-bit\n' | |
| 3464 ' builds. If an object’s "__hash__()" must ' | |
| 3465 'interoperate on builds\n' | |
| 3466 ' of different bit sizes, be sure to check the width on ' | |
| 3467 'all\n' | |
| 3468 ' supported builds. An easy way to do this is with ' | |
| 3469 '"python -c\n' | |
| 3470 ' "import sys; print(sys.hash_info.width)"".\n' | |
| 3471 '\n' | |
| 3472 ' If a class does not define an "__eq__()" method it ' | |
| 3473 'should not\n' | |
| 3474 ' define a "__hash__()" operation either; if it defines ' | |
| 3475 '"__eq__()"\n' | |
| 3476 ' but not "__hash__()", its instances will not be usable ' | |
| 3477 'as items in\n' | |
| 3478 ' hashable collections. If a class defines mutable ' | |
| 3479 'objects and\n' | |
| 3480 ' implements an "__eq__()" method, it should not ' | |
| 3481 'implement\n' | |
| 3482 ' "__hash__()", since the implementation of hashable ' | |
| 3483 'collections\n' | |
| 3484 ' requires that a key’s hash value is immutable (if the ' | |
| 3485 'object’s hash\n' | |
| 3486 ' value changes, it will be in the wrong hash bucket).\n' | |
| 3487 '\n' | |
| 3488 ' User-defined classes have "__eq__()" and "__hash__()" ' | |
| 3489 'methods by\n' | |
| 3490 ' default; with them, all objects compare unequal (except ' | |
| 3491 'with\n' | |
| 3492 ' themselves) and "x.__hash__()" returns an appropriate ' | |
| 3493 'value such\n' | |
| 3494 ' that "x == y" implies both that "x is y" and "hash(x) == ' | |
| 3495 'hash(y)".\n' | |
| 3496 '\n' | |
| 3497 ' A class that overrides "__eq__()" and does not define ' | |
| 3498 '"__hash__()"\n' | |
| 3499 ' will have its "__hash__()" implicitly set to "None". ' | |
| 3500 'When the\n' | |
| 3501 ' "__hash__()" method of a class is "None", instances of ' | |
| 3502 'the class\n' | |
| 3503 ' will raise an appropriate "TypeError" when a program ' | |
| 3504 'attempts to\n' | |
| 3505 ' retrieve their hash value, and will also be correctly ' | |
| 3506 'identified as\n' | |
| 3507 ' unhashable when checking "isinstance(obj,\n' | |
| 3508 ' collections.abc.Hashable)".\n' | |
| 3509 '\n' | |
| 3510 ' If a class that overrides "__eq__()" needs to retain ' | |
| 3511 'the\n' | |
| 3512 ' implementation of "__hash__()" from a parent class, the ' | |
| 3513 'interpreter\n' | |
| 3514 ' must be told this explicitly by setting "__hash__ =\n' | |
| 3515 ' <ParentClass>.__hash__".\n' | |
| 3516 '\n' | |
| 3517 ' If a class that does not override "__eq__()" wishes to ' | |
| 3518 'suppress\n' | |
| 3519 ' hash support, it should include "__hash__ = None" in the ' | |
| 3520 'class\n' | |
| 3521 ' definition. A class which defines its own "__hash__()" ' | |
| 3522 'that\n' | |
| 3523 ' explicitly raises a "TypeError" would be incorrectly ' | |
| 3524 'identified as\n' | |
| 3525 ' hashable by an "isinstance(obj, ' | |
| 3526 'collections.abc.Hashable)" call.\n' | |
| 3527 '\n' | |
| 3528 ' Note: By default, the "__hash__()" values of str and ' | |
| 3529 'bytes\n' | |
| 3530 ' objects are “salted” with an unpredictable random ' | |
| 3531 'value.\n' | |
| 3532 ' Although they remain constant within an individual ' | |
| 3533 'Python\n' | |
| 3534 ' process, they are not predictable between repeated ' | |
| 3535 'invocations of\n' | |
| 3536 ' Python.This is intended to provide protection against ' | |
| 3537 'a denial-\n' | |
| 3538 ' of-service caused by carefully-chosen inputs that ' | |
| 3539 'exploit the\n' | |
| 3540 ' worst case performance of a dict insertion, O(n^2) ' | |
| 3541 'complexity.\n' | |
| 3542 ' See ' | |
| 3543 'http://www.ocert.org/advisories/ocert-2011-003.html for\n' | |
| 3544 ' details.Changing hash values affects the iteration ' | |
| 3545 'order of sets.\n' | |
| 3546 ' Python has never made guarantees about this ordering ' | |
| 3547 '(and it\n' | |
| 3548 ' typically varies between 32-bit and 64-bit builds).See ' | |
| 3549 'also\n' | |
| 3550 ' "PYTHONHASHSEED".\n' | |
| 3551 '\n' | |
| 3552 ' Changed in version 3.3: Hash randomization is enabled by ' | |
| 3553 'default.\n' | |
| 3554 '\n' | |
| 3555 'object.__bool__(self)\n' | |
| 3556 '\n' | |
| 3557 ' Called to implement truth value testing and the built-in ' | |
| 3558 'operation\n' | |
| 3559 ' "bool()"; should return "False" or "True". When this ' | |
| 3560 'method is not\n' | |
| 3561 ' defined, "__len__()" is called, if it is defined, and ' | |
| 3562 'the object is\n' | |
| 3563 ' considered true if its result is nonzero. If a class ' | |
| 3564 'defines\n' | |
| 3565 ' neither "__len__()" nor "__bool__()", all its instances ' | |
| 3566 'are\n' | |
| 3567 ' considered true.\n', | |
| 3568 'debugger': '"pdb" — The Python Debugger\n' | |
| 3569 '***************************\n' | |
| 3570 '\n' | |
| 3571 '**Source code:** Lib/pdb.py\n' | |
| 3572 '\n' | |
| 3573 '======================================================================\n' | |
| 3574 '\n' | |
| 3575 'The module "pdb" defines an interactive source code debugger ' | |
| 3576 'for\n' | |
| 3577 'Python programs. It supports setting (conditional) breakpoints ' | |
| 3578 'and\n' | |
| 3579 'single stepping at the source line level, inspection of stack ' | |
| 3580 'frames,\n' | |
| 3581 'source code listing, and evaluation of arbitrary Python code in ' | |
| 3582 'the\n' | |
| 3583 'context of any stack frame. It also supports post-mortem ' | |
| 3584 'debugging\n' | |
| 3585 'and can be called under program control.\n' | |
| 3586 '\n' | |
| 3587 'The debugger is extensible – it is actually defined as the ' | |
| 3588 'class\n' | |
| 3589 '"Pdb". This is currently undocumented but easily understood by ' | |
| 3590 'reading\n' | |
| 3591 'the source. The extension interface uses the modules "bdb" and ' | |
| 3592 '"cmd".\n' | |
| 3593 '\n' | |
| 3594 'The debugger’s prompt is "(Pdb)". Typical usage to run a program ' | |
| 3595 'under\n' | |
| 3596 'control of the debugger is:\n' | |
| 3597 '\n' | |
| 3598 ' >>> import pdb\n' | |
| 3599 ' >>> import mymodule\n' | |
| 3600 " >>> pdb.run('mymodule.test()')\n" | |
| 3601 ' > <string>(0)?()\n' | |
| 3602 ' (Pdb) continue\n' | |
| 3603 ' > <string>(1)?()\n' | |
| 3604 ' (Pdb) continue\n' | |
| 3605 " NameError: 'spam'\n" | |
| 3606 ' > <string>(1)?()\n' | |
| 3607 ' (Pdb)\n' | |
| 3608 '\n' | |
| 3609 'Changed in version 3.3: Tab-completion via the "readline" module ' | |
| 3610 'is\n' | |
| 3611 'available for commands and command arguments, e.g. the current ' | |
| 3612 'global\n' | |
| 3613 'and local names are offered as arguments of the "p" command.\n' | |
| 3614 '\n' | |
| 3615 '"pdb.py" can also be invoked as a script to debug other ' | |
| 3616 'scripts. For\n' | |
| 3617 'example:\n' | |
| 3618 '\n' | |
| 3619 ' python3 -m pdb myscript.py\n' | |
| 3620 '\n' | |
| 3621 'When invoked as a script, pdb will automatically enter ' | |
| 3622 'post-mortem\n' | |
| 3623 'debugging if the program being debugged exits abnormally. After ' | |
| 3624 'post-\n' | |
| 3625 'mortem debugging (or after normal exit of the program), pdb ' | |
| 3626 'will\n' | |
| 3627 'restart the program. Automatic restarting preserves pdb’s state ' | |
| 3628 '(such\n' | |
| 3629 'as breakpoints) and in most cases is more useful than quitting ' | |
| 3630 'the\n' | |
| 3631 'debugger upon program’s exit.\n' | |
| 3632 '\n' | |
| 3633 'New in version 3.2: "pdb.py" now accepts a "-c" option that ' | |
| 3634 'executes\n' | |
| 3635 'commands as if given in a ".pdbrc" file, see Debugger Commands.\n' | |
| 3636 '\n' | |
| 3637 'New in version 3.7: "pdb.py" now accepts a "-m" option that ' | |
| 3638 'execute\n' | |
| 3639 'modules similar to the way "python3 -m" does. As with a script, ' | |
| 3640 'the\n' | |
| 3641 'debugger will pause execution just before the first line of the\n' | |
| 3642 'module.\n' | |
| 3643 '\n' | |
| 3644 'The typical usage to break into the debugger from a running ' | |
| 3645 'program is\n' | |
| 3646 'to insert\n' | |
| 3647 '\n' | |
| 3648 ' import pdb; pdb.set_trace()\n' | |
| 3649 '\n' | |
| 3650 'at the location you want to break into the debugger. You can ' | |
| 3651 'then\n' | |
| 3652 'step through the code following this statement, and continue ' | |
| 3653 'running\n' | |
| 3654 'without the debugger using the "continue" command.\n' | |
| 3655 '\n' | |
| 3656 'New in version 3.7: The built-in "breakpoint()", when called ' | |
| 3657 'with\n' | |
| 3658 'defaults, can be used instead of "import pdb; pdb.set_trace()".\n' | |
| 3659 '\n' | |
| 3660 'The typical usage to inspect a crashed program is:\n' | |
| 3661 '\n' | |
| 3662 ' >>> import pdb\n' | |
| 3663 ' >>> import mymodule\n' | |
| 3664 ' >>> mymodule.test()\n' | |
| 3665 ' Traceback (most recent call last):\n' | |
| 3666 ' File "<stdin>", line 1, in <module>\n' | |
| 3667 ' File "./mymodule.py", line 4, in test\n' | |
| 3668 ' test2()\n' | |
| 3669 ' File "./mymodule.py", line 3, in test2\n' | |
| 3670 ' print(spam)\n' | |
| 3671 ' NameError: spam\n' | |
| 3672 ' >>> pdb.pm()\n' | |
| 3673 ' > ./mymodule.py(3)test2()\n' | |
| 3674 ' -> print(spam)\n' | |
| 3675 ' (Pdb)\n' | |
| 3676 '\n' | |
| 3677 'The module defines the following functions; each enters the ' | |
| 3678 'debugger\n' | |
| 3679 'in a slightly different way:\n' | |
| 3680 '\n' | |
| 3681 'pdb.run(statement, globals=None, locals=None)\n' | |
| 3682 '\n' | |
| 3683 ' Execute the *statement* (given as a string or a code object) ' | |
| 3684 'under\n' | |
| 3685 ' debugger control. The debugger prompt appears before any ' | |
| 3686 'code is\n' | |
| 3687 ' executed; you can set breakpoints and type "continue", or you ' | |
| 3688 'can\n' | |
| 3689 ' step through the statement using "step" or "next" (all these\n' | |
| 3690 ' commands are explained below). The optional *globals* and ' | |
| 3691 '*locals*\n' | |
| 3692 ' arguments specify the environment in which the code is ' | |
| 3693 'executed; by\n' | |
| 3694 ' default the dictionary of the module "__main__" is used. ' | |
| 3695 '(See the\n' | |
| 3696 ' explanation of the built-in "exec()" or "eval()" functions.)\n' | |
| 3697 '\n' | |
| 3698 'pdb.runeval(expression, globals=None, locals=None)\n' | |
| 3699 '\n' | |
| 3700 ' Evaluate the *expression* (given as a string or a code ' | |
| 3701 'object)\n' | |
| 3702 ' under debugger control. When "runeval()" returns, it returns ' | |
| 3703 'the\n' | |
| 3704 ' value of the expression. Otherwise this function is similar ' | |
| 3705 'to\n' | |
| 3706 ' "run()".\n' | |
| 3707 '\n' | |
| 3708 'pdb.runcall(function, *args, **kwds)\n' | |
| 3709 '\n' | |
| 3710 ' Call the *function* (a function or method object, not a ' | |
| 3711 'string)\n' | |
| 3712 ' with the given arguments. When "runcall()" returns, it ' | |
| 3713 'returns\n' | |
| 3714 ' whatever the function call returned. The debugger prompt ' | |
| 3715 'appears\n' | |
| 3716 ' as soon as the function is entered.\n' | |
| 3717 '\n' | |
| 3718 'pdb.set_trace(*, header=None)\n' | |
| 3719 '\n' | |
| 3720 ' Enter the debugger at the calling stack frame. This is ' | |
| 3721 'useful to\n' | |
| 3722 ' hard-code a breakpoint at a given point in a program, even if ' | |
| 3723 'the\n' | |
| 3724 ' code is not otherwise being debugged (e.g. when an assertion\n' | |
| 3725 ' fails). If given, *header* is printed to the console just ' | |
| 3726 'before\n' | |
| 3727 ' debugging begins.\n' | |
| 3728 '\n' | |
| 3729 ' Changed in version 3.7: The keyword-only argument *header*.\n' | |
| 3730 '\n' | |
| 3731 'pdb.post_mortem(traceback=None)\n' | |
| 3732 '\n' | |
| 3733 ' Enter post-mortem debugging of the given *traceback* object. ' | |
| 3734 'If no\n' | |
| 3735 ' *traceback* is given, it uses the one of the exception that ' | |
| 3736 'is\n' | |
| 3737 ' currently being handled (an exception must be being handled ' | |
| 3738 'if the\n' | |
| 3739 ' default is to be used).\n' | |
| 3740 '\n' | |
| 3741 'pdb.pm()\n' | |
| 3742 '\n' | |
| 3743 ' Enter post-mortem debugging of the traceback found in\n' | |
| 3744 ' "sys.last_traceback".\n' | |
| 3745 '\n' | |
| 3746 'The "run*" functions and "set_trace()" are aliases for ' | |
| 3747 'instantiating\n' | |
| 3748 'the "Pdb" class and calling the method of the same name. If you ' | |
| 3749 'want\n' | |
| 3750 'to access further features, you have to do this yourself:\n' | |
| 3751 '\n' | |
| 3752 "class pdb.Pdb(completekey='tab', stdin=None, stdout=None, " | |
| 3753 'skip=None, nosigint=False, readrc=True)\n' | |
| 3754 '\n' | |
| 3755 ' "Pdb" is the debugger class.\n' | |
| 3756 '\n' | |
| 3757 ' The *completekey*, *stdin* and *stdout* arguments are passed ' | |
| 3758 'to the\n' | |
| 3759 ' underlying "cmd.Cmd" class; see the description there.\n' | |
| 3760 '\n' | |
| 3761 ' The *skip* argument, if given, must be an iterable of ' | |
| 3762 'glob-style\n' | |
| 3763 ' module name patterns. The debugger will not step into frames ' | |
| 3764 'that\n' | |
| 3765 ' originate in a module that matches one of these patterns. ' | |
| 3766 '[1]\n' | |
| 3767 '\n' | |
| 3768 ' By default, Pdb sets a handler for the SIGINT signal (which ' | |
| 3769 'is sent\n' | |
| 3770 ' when the user presses "Ctrl-C" on the console) when you give ' | |
| 3771 'a\n' | |
| 3772 ' "continue" command. This allows you to break into the ' | |
| 3773 'debugger\n' | |
| 3774 ' again by pressing "Ctrl-C". If you want Pdb not to touch ' | |
| 3775 'the\n' | |
| 3776 ' SIGINT handler, set *nosigint* to true.\n' | |
| 3777 '\n' | |
| 3778 ' The *readrc* argument defaults to true and controls whether ' | |
| 3779 'Pdb\n' | |
| 3780 ' will load .pdbrc files from the filesystem.\n' | |
| 3781 '\n' | |
| 3782 ' Example call to enable tracing with *skip*:\n' | |
| 3783 '\n' | |
| 3784 " import pdb; pdb.Pdb(skip=['django.*']).set_trace()\n" | |
| 3785 '\n' | |
| 3786 ' Raises an auditing event "pdb.Pdb" with no arguments.\n' | |
| 3787 '\n' | |
| 3788 ' New in version 3.1: The *skip* argument.\n' | |
| 3789 '\n' | |
| 3790 ' New in version 3.2: The *nosigint* argument. Previously, a ' | |
| 3791 'SIGINT\n' | |
| 3792 ' handler was never set by Pdb.\n' | |
| 3793 '\n' | |
| 3794 ' Changed in version 3.6: The *readrc* argument.\n' | |
| 3795 '\n' | |
| 3796 ' run(statement, globals=None, locals=None)\n' | |
| 3797 ' runeval(expression, globals=None, locals=None)\n' | |
| 3798 ' runcall(function, *args, **kwds)\n' | |
| 3799 ' set_trace()\n' | |
| 3800 '\n' | |
| 3801 ' See the documentation for the functions explained above.\n' | |
| 3802 '\n' | |
| 3803 '\n' | |
| 3804 'Debugger Commands\n' | |
| 3805 '=================\n' | |
| 3806 '\n' | |
| 3807 'The commands recognized by the debugger are listed below. Most\n' | |
| 3808 'commands can be abbreviated to one or two letters as indicated; ' | |
| 3809 'e.g.\n' | |
| 3810 '"h(elp)" means that either "h" or "help" can be used to enter ' | |
| 3811 'the help\n' | |
| 3812 'command (but not "he" or "hel", nor "H" or "Help" or "HELP").\n' | |
| 3813 'Arguments to commands must be separated by whitespace (spaces ' | |
| 3814 'or\n' | |
| 3815 'tabs). Optional arguments are enclosed in square brackets ' | |
| 3816 '("[]") in\n' | |
| 3817 'the command syntax; the square brackets must not be typed.\n' | |
| 3818 'Alternatives in the command syntax are separated by a vertical ' | |
| 3819 'bar\n' | |
| 3820 '("|").\n' | |
| 3821 '\n' | |
| 3822 'Entering a blank line repeats the last command entered. ' | |
| 3823 'Exception: if\n' | |
| 3824 'the last command was a "list" command, the next 11 lines are ' | |
| 3825 'listed.\n' | |
| 3826 '\n' | |
| 3827 'Commands that the debugger doesn’t recognize are assumed to be ' | |
| 3828 'Python\n' | |
| 3829 'statements and are executed in the context of the program being\n' | |
| 3830 'debugged. Python statements can also be prefixed with an ' | |
| 3831 'exclamation\n' | |
| 3832 'point ("!"). This is a powerful way to inspect the program ' | |
| 3833 'being\n' | |
| 3834 'debugged; it is even possible to change a variable or call a ' | |
| 3835 'function.\n' | |
| 3836 'When an exception occurs in such a statement, the exception name ' | |
| 3837 'is\n' | |
| 3838 'printed but the debugger’s state is not changed.\n' | |
| 3839 '\n' | |
| 3840 'The debugger supports aliases. Aliases can have parameters ' | |
| 3841 'which\n' | |
| 3842 'allows one a certain level of adaptability to the context under\n' | |
| 3843 'examination.\n' | |
| 3844 '\n' | |
| 3845 'Multiple commands may be entered on a single line, separated by ' | |
| 3846 '";;".\n' | |
| 3847 '(A single ";" is not used as it is the separator for multiple ' | |
| 3848 'commands\n' | |
| 3849 'in a line that is passed to the Python parser.) No intelligence ' | |
| 3850 'is\n' | |
| 3851 'applied to separating the commands; the input is split at the ' | |
| 3852 'first\n' | |
| 3853 '";;" pair, even if it is in the middle of a quoted string.\n' | |
| 3854 '\n' | |
| 3855 'If a file ".pdbrc" exists in the user’s home directory or in ' | |
| 3856 'the\n' | |
| 3857 'current directory, it is read in and executed as if it had been ' | |
| 3858 'typed\n' | |
| 3859 'at the debugger prompt. This is particularly useful for ' | |
| 3860 'aliases. If\n' | |
| 3861 'both files exist, the one in the home directory is read first ' | |
| 3862 'and\n' | |
| 3863 'aliases defined there can be overridden by the local file.\n' | |
| 3864 '\n' | |
| 3865 'Changed in version 3.2: ".pdbrc" can now contain commands that\n' | |
| 3866 'continue debugging, such as "continue" or "next". Previously, ' | |
| 3867 'these\n' | |
| 3868 'commands had no effect.\n' | |
| 3869 '\n' | |
| 3870 'h(elp) [command]\n' | |
| 3871 '\n' | |
| 3872 ' Without argument, print the list of available commands. With ' | |
| 3873 'a\n' | |
| 3874 ' *command* as argument, print help about that command. "help ' | |
| 3875 'pdb"\n' | |
| 3876 ' displays the full documentation (the docstring of the "pdb"\n' | |
| 3877 ' module). Since the *command* argument must be an identifier, ' | |
| 3878 '"help\n' | |
| 3879 ' exec" must be entered to get help on the "!" command.\n' | |
| 3880 '\n' | |
| 3881 'w(here)\n' | |
| 3882 '\n' | |
| 3883 ' Print a stack trace, with the most recent frame at the ' | |
| 3884 'bottom. An\n' | |
| 3885 ' arrow indicates the current frame, which determines the ' | |
| 3886 'context of\n' | |
| 3887 ' most commands.\n' | |
| 3888 '\n' | |
| 3889 'd(own) [count]\n' | |
| 3890 '\n' | |
| 3891 ' Move the current frame *count* (default one) levels down in ' | |
| 3892 'the\n' | |
| 3893 ' stack trace (to a newer frame).\n' | |
| 3894 '\n' | |
| 3895 'u(p) [count]\n' | |
| 3896 '\n' | |
| 3897 ' Move the current frame *count* (default one) levels up in the ' | |
| 3898 'stack\n' | |
| 3899 ' trace (to an older frame).\n' | |
| 3900 '\n' | |
| 3901 'b(reak) [([filename:]lineno | function) [, condition]]\n' | |
| 3902 '\n' | |
| 3903 ' With a *lineno* argument, set a break there in the current ' | |
| 3904 'file.\n' | |
| 3905 ' With a *function* argument, set a break at the first ' | |
| 3906 'executable\n' | |
| 3907 ' statement within that function. The line number may be ' | |
| 3908 'prefixed\n' | |
| 3909 ' with a filename and a colon, to specify a breakpoint in ' | |
| 3910 'another\n' | |
| 3911 ' file (probably one that hasn’t been loaded yet). The file ' | |
| 3912 'is\n' | |
| 3913 ' searched on "sys.path". Note that each breakpoint is ' | |
| 3914 'assigned a\n' | |
| 3915 ' number to which all the other breakpoint commands refer.\n' | |
| 3916 '\n' | |
| 3917 ' If a second argument is present, it is an expression which ' | |
| 3918 'must\n' | |
| 3919 ' evaluate to true before the breakpoint is honored.\n' | |
| 3920 '\n' | |
| 3921 ' Without argument, list all breaks, including for each ' | |
| 3922 'breakpoint,\n' | |
| 3923 ' the number of times that breakpoint has been hit, the ' | |
| 3924 'current\n' | |
| 3925 ' ignore count, and the associated condition if any.\n' | |
| 3926 '\n' | |
| 3927 'tbreak [([filename:]lineno | function) [, condition]]\n' | |
| 3928 '\n' | |
| 3929 ' Temporary breakpoint, which is removed automatically when it ' | |
| 3930 'is\n' | |
| 3931 ' first hit. The arguments are the same as for "break".\n' | |
| 3932 '\n' | |
| 3933 'cl(ear) [filename:lineno | bpnumber [bpnumber ...]]\n' | |
| 3934 '\n' | |
| 3935 ' With a *filename:lineno* argument, clear all the breakpoints ' | |
| 3936 'at\n' | |
| 3937 ' this line. With a space separated list of breakpoint numbers, ' | |
| 3938 'clear\n' | |
| 3939 ' those breakpoints. Without argument, clear all breaks (but ' | |
| 3940 'first\n' | |
| 3941 ' ask confirmation).\n' | |
| 3942 '\n' | |
| 3943 'disable [bpnumber [bpnumber ...]]\n' | |
| 3944 '\n' | |
| 3945 ' Disable the breakpoints given as a space separated list of\n' | |
| 3946 ' breakpoint numbers. Disabling a breakpoint means it cannot ' | |
| 3947 'cause\n' | |
| 3948 ' the program to stop execution, but unlike clearing a ' | |
| 3949 'breakpoint, it\n' | |
| 3950 ' remains in the list of breakpoints and can be (re-)enabled.\n' | |
| 3951 '\n' | |
| 3952 'enable [bpnumber [bpnumber ...]]\n' | |
| 3953 '\n' | |
| 3954 ' Enable the breakpoints specified.\n' | |
| 3955 '\n' | |
| 3956 'ignore bpnumber [count]\n' | |
| 3957 '\n' | |
| 3958 ' Set the ignore count for the given breakpoint number. If ' | |
| 3959 'count is\n' | |
| 3960 ' omitted, the ignore count is set to 0. A breakpoint becomes ' | |
| 3961 'active\n' | |
| 3962 ' when the ignore count is zero. When non-zero, the count is\n' | |
| 3963 ' decremented each time the breakpoint is reached and the ' | |
| 3964 'breakpoint\n' | |
| 3965 ' is not disabled and any associated condition evaluates to ' | |
| 3966 'true.\n' | |
| 3967 '\n' | |
| 3968 'condition bpnumber [condition]\n' | |
| 3969 '\n' | |
| 3970 ' Set a new *condition* for the breakpoint, an expression which ' | |
| 3971 'must\n' | |
| 3972 ' evaluate to true before the breakpoint is honored. If ' | |
| 3973 '*condition*\n' | |
| 3974 ' is absent, any existing condition is removed; i.e., the ' | |
| 3975 'breakpoint\n' | |
| 3976 ' is made unconditional.\n' | |
| 3977 '\n' | |
| 3978 'commands [bpnumber]\n' | |
| 3979 '\n' | |
| 3980 ' Specify a list of commands for breakpoint number *bpnumber*. ' | |
| 3981 'The\n' | |
| 3982 ' commands themselves appear on the following lines. Type a ' | |
| 3983 'line\n' | |
| 3984 ' containing just "end" to terminate the commands. An example:\n' | |
| 3985 '\n' | |
| 3986 ' (Pdb) commands 1\n' | |
| 3987 ' (com) p some_variable\n' | |
| 3988 ' (com) end\n' | |
| 3989 ' (Pdb)\n' | |
| 3990 '\n' | |
| 3991 ' To remove all commands from a breakpoint, type "commands" ' | |
| 3992 'and\n' | |
| 3993 ' follow it immediately with "end"; that is, give no commands.\n' | |
| 3994 '\n' | |
| 3995 ' With no *bpnumber* argument, "commands" refers to the last\n' | |
| 3996 ' breakpoint set.\n' | |
| 3997 '\n' | |
| 3998 ' You can use breakpoint commands to start your program up ' | |
| 3999 'again.\n' | |
| 4000 ' Simply use the "continue" command, or "step", or any other ' | |
| 4001 'command\n' | |
| 4002 ' that resumes execution.\n' | |
| 4003 '\n' | |
| 4004 ' Specifying any command resuming execution (currently ' | |
| 4005 '"continue",\n' | |
| 4006 ' "step", "next", "return", "jump", "quit" and their ' | |
| 4007 'abbreviations)\n' | |
| 4008 ' terminates the command list (as if that command was ' | |
| 4009 'immediately\n' | |
| 4010 ' followed by end). This is because any time you resume ' | |
| 4011 'execution\n' | |
| 4012 ' (even with a simple next or step), you may encounter another\n' | |
| 4013 ' breakpoint—which could have its own command list, leading to\n' | |
| 4014 ' ambiguities about which list to execute.\n' | |
| 4015 '\n' | |
| 4016 ' If you use the ‘silent’ command in the command list, the ' | |
| 4017 'usual\n' | |
| 4018 ' message about stopping at a breakpoint is not printed. This ' | |
| 4019 'may be\n' | |
| 4020 ' desirable for breakpoints that are to print a specific ' | |
| 4021 'message and\n' | |
| 4022 ' then continue. If none of the other commands print anything, ' | |
| 4023 'you\n' | |
| 4024 ' see no sign that the breakpoint was reached.\n' | |
| 4025 '\n' | |
| 4026 's(tep)\n' | |
| 4027 '\n' | |
| 4028 ' Execute the current line, stop at the first possible ' | |
| 4029 'occasion\n' | |
| 4030 ' (either in a function that is called or on the next line in ' | |
| 4031 'the\n' | |
| 4032 ' current function).\n' | |
| 4033 '\n' | |
| 4034 'n(ext)\n' | |
| 4035 '\n' | |
| 4036 ' Continue execution until the next line in the current ' | |
| 4037 'function is\n' | |
| 4038 ' reached or it returns. (The difference between "next" and ' | |
| 4039 '"step"\n' | |
| 4040 ' is that "step" stops inside a called function, while "next"\n' | |
| 4041 ' executes called functions at (nearly) full speed, only ' | |
| 4042 'stopping at\n' | |
| 4043 ' the next line in the current function.)\n' | |
| 4044 '\n' | |
| 4045 'unt(il) [lineno]\n' | |
| 4046 '\n' | |
| 4047 ' Without argument, continue execution until the line with a ' | |
| 4048 'number\n' | |
| 4049 ' greater than the current one is reached.\n' | |
| 4050 '\n' | |
| 4051 ' With a line number, continue execution until a line with a ' | |
| 4052 'number\n' | |
| 4053 ' greater or equal to that is reached. In both cases, also ' | |
| 4054 'stop when\n' | |
| 4055 ' the current frame returns.\n' | |
| 4056 '\n' | |
| 4057 ' Changed in version 3.2: Allow giving an explicit line ' | |
| 4058 'number.\n' | |
| 4059 '\n' | |
| 4060 'r(eturn)\n' | |
| 4061 '\n' | |
| 4062 ' Continue execution until the current function returns.\n' | |
| 4063 '\n' | |
| 4064 'c(ont(inue))\n' | |
| 4065 '\n' | |
| 4066 ' Continue execution, only stop when a breakpoint is ' | |
| 4067 'encountered.\n' | |
| 4068 '\n' | |
| 4069 'j(ump) lineno\n' | |
| 4070 '\n' | |
| 4071 ' Set the next line that will be executed. Only available in ' | |
| 4072 'the\n' | |
| 4073 ' bottom-most frame. This lets you jump back and execute code ' | |
| 4074 'again,\n' | |
| 4075 ' or jump forward to skip code that you don’t want to run.\n' | |
| 4076 '\n' | |
| 4077 ' It should be noted that not all jumps are allowed – for ' | |
| 4078 'instance it\n' | |
| 4079 ' is not possible to jump into the middle of a "for" loop or ' | |
| 4080 'out of a\n' | |
| 4081 ' "finally" clause.\n' | |
| 4082 '\n' | |
| 4083 'l(ist) [first[, last]]\n' | |
| 4084 '\n' | |
| 4085 ' List source code for the current file. Without arguments, ' | |
| 4086 'list 11\n' | |
| 4087 ' lines around the current line or continue the previous ' | |
| 4088 'listing.\n' | |
| 4089 ' With "." as argument, list 11 lines around the current line. ' | |
| 4090 'With\n' | |
| 4091 ' one argument, list 11 lines around at that line. With two\n' | |
| 4092 ' arguments, list the given range; if the second argument is ' | |
| 4093 'less\n' | |
| 4094 ' than the first, it is interpreted as a count.\n' | |
| 4095 '\n' | |
| 4096 ' The current line in the current frame is indicated by "->". ' | |
| 4097 'If an\n' | |
| 4098 ' exception is being debugged, the line where the exception ' | |
| 4099 'was\n' | |
| 4100 ' originally raised or propagated is indicated by ">>", if it ' | |
| 4101 'differs\n' | |
| 4102 ' from the current line.\n' | |
| 4103 '\n' | |
| 4104 ' New in version 3.2: The ">>" marker.\n' | |
| 4105 '\n' | |
| 4106 'll | longlist\n' | |
| 4107 '\n' | |
| 4108 ' List all source code for the current function or frame.\n' | |
| 4109 ' Interesting lines are marked as for "list".\n' | |
| 4110 '\n' | |
| 4111 ' New in version 3.2.\n' | |
| 4112 '\n' | |
| 4113 'a(rgs)\n' | |
| 4114 '\n' | |
| 4115 ' Print the argument list of the current function.\n' | |
| 4116 '\n' | |
| 4117 'p expression\n' | |
| 4118 '\n' | |
| 4119 ' Evaluate the *expression* in the current context and print ' | |
| 4120 'its\n' | |
| 4121 ' value.\n' | |
| 4122 '\n' | |
| 4123 ' Note: "print()" can also be used, but is not a debugger ' | |
| 4124 'command —\n' | |
| 4125 ' this executes the Python "print()" function.\n' | |
| 4126 '\n' | |
| 4127 'pp expression\n' | |
| 4128 '\n' | |
| 4129 ' Like the "p" command, except the value of the expression is ' | |
| 4130 'pretty-\n' | |
| 4131 ' printed using the "pprint" module.\n' | |
| 4132 '\n' | |
| 4133 'whatis expression\n' | |
| 4134 '\n' | |
| 4135 ' Print the type of the *expression*.\n' | |
| 4136 '\n' | |
| 4137 'source expression\n' | |
| 4138 '\n' | |
| 4139 ' Try to get source code for the given object and display it.\n' | |
| 4140 '\n' | |
| 4141 ' New in version 3.2.\n' | |
| 4142 '\n' | |
| 4143 'display [expression]\n' | |
| 4144 '\n' | |
| 4145 ' Display the value of the expression if it changed, each time\n' | |
| 4146 ' execution stops in the current frame.\n' | |
| 4147 '\n' | |
| 4148 ' Without expression, list all display expressions for the ' | |
| 4149 'current\n' | |
| 4150 ' frame.\n' | |
| 4151 '\n' | |
| 4152 ' New in version 3.2.\n' | |
| 4153 '\n' | |
| 4154 'undisplay [expression]\n' | |
| 4155 '\n' | |
| 4156 ' Do not display the expression any more in the current frame.\n' | |
| 4157 ' Without expression, clear all display expressions for the ' | |
| 4158 'current\n' | |
| 4159 ' frame.\n' | |
| 4160 '\n' | |
| 4161 ' New in version 3.2.\n' | |
| 4162 '\n' | |
| 4163 'interact\n' | |
| 4164 '\n' | |
| 4165 ' Start an interactive interpreter (using the "code" module) ' | |
| 4166 'whose\n' | |
| 4167 ' global namespace contains all the (global and local) names ' | |
| 4168 'found in\n' | |
| 4169 ' the current scope.\n' | |
| 4170 '\n' | |
| 4171 ' New in version 3.2.\n' | |
| 4172 '\n' | |
| 4173 'alias [name [command]]\n' | |
| 4174 '\n' | |
| 4175 ' Create an alias called *name* that executes *command*. The ' | |
| 4176 'command\n' | |
| 4177 ' must *not* be enclosed in quotes. Replaceable parameters can ' | |
| 4178 'be\n' | |
| 4179 ' indicated by "%1", "%2", and so on, while "%*" is replaced by ' | |
| 4180 'all\n' | |
| 4181 ' the parameters. If no command is given, the current alias ' | |
| 4182 'for\n' | |
| 4183 ' *name* is shown. If no arguments are given, all aliases are ' | |
| 4184 'listed.\n' | |
| 4185 '\n' | |
| 4186 ' Aliases may be nested and can contain anything that can be ' | |
| 4187 'legally\n' | |
| 4188 ' typed at the pdb prompt. Note that internal pdb commands ' | |
| 4189 '*can* be\n' | |
| 4190 ' overridden by aliases. Such a command is then hidden until ' | |
| 4191 'the\n' | |
| 4192 ' alias is removed. Aliasing is recursively applied to the ' | |
| 4193 'first\n' | |
| 4194 ' word of the command line; all other words in the line are ' | |
| 4195 'left\n' | |
| 4196 ' alone.\n' | |
| 4197 '\n' | |
| 4198 ' As an example, here are two useful aliases (especially when ' | |
| 4199 'placed\n' | |
| 4200 ' in the ".pdbrc" file):\n' | |
| 4201 '\n' | |
| 4202 ' # Print instance variables (usage "pi classInst")\n' | |
| 4203 ' alias pi for k in %1.__dict__.keys(): ' | |
| 4204 'print("%1.",k,"=",%1.__dict__[k])\n' | |
| 4205 ' # Print instance variables in self\n' | |
| 4206 ' alias ps pi self\n' | |
| 4207 '\n' | |
| 4208 'unalias name\n' | |
| 4209 '\n' | |
| 4210 ' Delete the specified alias.\n' | |
| 4211 '\n' | |
| 4212 '! statement\n' | |
| 4213 '\n' | |
| 4214 ' Execute the (one-line) *statement* in the context of the ' | |
| 4215 'current\n' | |
| 4216 ' stack frame. The exclamation point can be omitted unless the ' | |
| 4217 'first\n' | |
| 4218 ' word of the statement resembles a debugger command. To set ' | |
| 4219 'a\n' | |
| 4220 ' global variable, you can prefix the assignment command with ' | |
| 4221 'a\n' | |
| 4222 ' "global" statement on the same line, e.g.:\n' | |
| 4223 '\n' | |
| 4224 " (Pdb) global list_options; list_options = ['-l']\n" | |
| 4225 ' (Pdb)\n' | |
| 4226 '\n' | |
| 4227 'run [args ...]\n' | |
| 4228 'restart [args ...]\n' | |
| 4229 '\n' | |
| 4230 ' Restart the debugged Python program. If an argument is ' | |
| 4231 'supplied,\n' | |
| 4232 ' it is split with "shlex" and the result is used as the new\n' | |
| 4233 ' "sys.argv". History, breakpoints, actions and debugger ' | |
| 4234 'options are\n' | |
| 4235 ' preserved. "restart" is an alias for "run".\n' | |
| 4236 '\n' | |
| 4237 'q(uit)\n' | |
| 4238 '\n' | |
| 4239 ' Quit from the debugger. The program being executed is ' | |
| 4240 'aborted.\n' | |
| 4241 '\n' | |
| 4242 'debug code\n' | |
| 4243 '\n' | |
| 4244 ' Enter a recursive debugger that steps through the code ' | |
| 4245 'argument\n' | |
| 4246 ' (which is an arbitrary expression or statement to be executed ' | |
| 4247 'in\n' | |
| 4248 ' the current environment).\n' | |
| 4249 '\n' | |
| 4250 'retval\n' | |
| 4251 'Print the return value for the last return of a function.\n' | |
| 4252 '\n' | |
| 4253 '-[ Footnotes ]-\n' | |
| 4254 '\n' | |
| 4255 '[1] Whether a frame is considered to originate in a certain ' | |
| 4256 'module\n' | |
| 4257 ' is determined by the "__name__" in the frame globals.\n', | |
| 4258 'del': 'The "del" statement\n' | |
| 4259 '*******************\n' | |
| 4260 '\n' | |
| 4261 ' del_stmt ::= "del" target_list\n' | |
| 4262 '\n' | |
| 4263 'Deletion is recursively defined very similar to the way assignment ' | |
| 4264 'is\n' | |
| 4265 'defined. Rather than spelling it out in full details, here are some\n' | |
| 4266 'hints.\n' | |
| 4267 '\n' | |
| 4268 'Deletion of a target list recursively deletes each target, from left\n' | |
| 4269 'to right.\n' | |
| 4270 '\n' | |
| 4271 'Deletion of a name removes the binding of that name from the local ' | |
| 4272 'or\n' | |
| 4273 'global namespace, depending on whether the name occurs in a "global"\n' | |
| 4274 'statement in the same code block. If the name is unbound, a\n' | |
| 4275 '"NameError" exception will be raised.\n' | |
| 4276 '\n' | |
| 4277 'Deletion of attribute references, subscriptions and slicings is ' | |
| 4278 'passed\n' | |
| 4279 'to the primary object involved; deletion of a slicing is in general\n' | |
| 4280 'equivalent to assignment of an empty slice of the right type (but ' | |
| 4281 'even\n' | |
| 4282 'this is determined by the sliced object).\n' | |
| 4283 '\n' | |
| 4284 'Changed in version 3.2: Previously it was illegal to delete a name\n' | |
| 4285 'from the local namespace if it occurs as a free variable in a nested\n' | |
| 4286 'block.\n', | |
| 4287 'dict': 'Dictionary displays\n' | |
| 4288 '*******************\n' | |
| 4289 '\n' | |
| 4290 'A dictionary display is a possibly empty series of key/datum pairs\n' | |
| 4291 'enclosed in curly braces:\n' | |
| 4292 '\n' | |
| 4293 ' dict_display ::= "{" [key_datum_list | dict_comprehension] ' | |
| 4294 '"}"\n' | |
| 4295 ' key_datum_list ::= key_datum ("," key_datum)* [","]\n' | |
| 4296 ' key_datum ::= expression ":" expression | "**" or_expr\n' | |
| 4297 ' dict_comprehension ::= expression ":" expression comp_for\n' | |
| 4298 '\n' | |
| 4299 'A dictionary display yields a new dictionary object.\n' | |
| 4300 '\n' | |
| 4301 'If a comma-separated sequence of key/datum pairs is given, they are\n' | |
| 4302 'evaluated from left to right to define the entries of the ' | |
| 4303 'dictionary:\n' | |
| 4304 'each key object is used as a key into the dictionary to store the\n' | |
| 4305 'corresponding datum. This means that you can specify the same key\n' | |
| 4306 'multiple times in the key/datum list, and the final dictionary’s ' | |
| 4307 'value\n' | |
| 4308 'for that key will be the last one given.\n' | |
| 4309 '\n' | |
| 4310 'A double asterisk "**" denotes *dictionary unpacking*. Its operand\n' | |
| 4311 'must be a *mapping*. Each mapping item is added to the new\n' | |
| 4312 'dictionary. Later values replace values already set by earlier\n' | |
| 4313 'key/datum pairs and earlier dictionary unpackings.\n' | |
| 4314 '\n' | |
| 4315 'New in version 3.5: Unpacking into dictionary displays, originally\n' | |
| 4316 'proposed by **PEP 448**.\n' | |
| 4317 '\n' | |
| 4318 'A dict comprehension, in contrast to list and set comprehensions,\n' | |
| 4319 'needs two expressions separated with a colon followed by the usual\n' | |
| 4320 '“for” and “if” clauses. When the comprehension is run, the ' | |
| 4321 'resulting\n' | |
| 4322 'key and value elements are inserted in the new dictionary in the ' | |
| 4323 'order\n' | |
| 4324 'they are produced.\n' | |
| 4325 '\n' | |
| 4326 'Restrictions on the types of the key values are listed earlier in\n' | |
| 4327 'section The standard type hierarchy. (To summarize, the key type\n' | |
| 4328 'should be *hashable*, which excludes all mutable objects.) Clashes\n' | |
| 4329 'between duplicate keys are not detected; the last datum (textually\n' | |
| 4330 'rightmost in the display) stored for a given key value prevails.\n' | |
| 4331 '\n' | |
| 4332 'Changed in version 3.8: Prior to Python 3.8, in dict ' | |
| 4333 'comprehensions,\n' | |
| 4334 'the evaluation order of key and value was not well-defined. In\n' | |
| 4335 'CPython, the value was evaluated before the key. Starting with ' | |
| 4336 '3.8,\n' | |
| 4337 'the key is evaluated before the value, as proposed by **PEP 572**.\n', | |
| 4338 'dynamic-features': 'Interaction with dynamic features\n' | |
| 4339 '*********************************\n' | |
| 4340 '\n' | |
| 4341 'Name resolution of free variables occurs at runtime, not ' | |
| 4342 'at compile\n' | |
| 4343 'time. This means that the following code will print 42:\n' | |
| 4344 '\n' | |
| 4345 ' i = 10\n' | |
| 4346 ' def f():\n' | |
| 4347 ' print(i)\n' | |
| 4348 ' i = 42\n' | |
| 4349 ' f()\n' | |
| 4350 '\n' | |
| 4351 'The "eval()" and "exec()" functions do not have access ' | |
| 4352 'to the full\n' | |
| 4353 'environment for resolving names. Names may be resolved ' | |
| 4354 'in the local\n' | |
| 4355 'and global namespaces of the caller. Free variables are ' | |
| 4356 'not resolved\n' | |
| 4357 'in the nearest enclosing namespace, but in the global ' | |
| 4358 'namespace. [1]\n' | |
| 4359 'The "exec()" and "eval()" functions have optional ' | |
| 4360 'arguments to\n' | |
| 4361 'override the global and local namespace. If only one ' | |
| 4362 'namespace is\n' | |
| 4363 'specified, it is used for both.\n', | |
| 4364 'else': 'The "if" statement\n' | |
| 4365 '******************\n' | |
| 4366 '\n' | |
| 4367 'The "if" statement is used for conditional execution:\n' | |
| 4368 '\n' | |
| 4369 ' if_stmt ::= "if" expression ":" suite\n' | |
| 4370 ' ("elif" expression ":" suite)*\n' | |
| 4371 ' ["else" ":" suite]\n' | |
| 4372 '\n' | |
| 4373 'It selects exactly one of the suites by evaluating the expressions ' | |
| 4374 'one\n' | |
| 4375 'by one until one is found to be true (see section Boolean ' | |
| 4376 'operations\n' | |
| 4377 'for the definition of true and false); then that suite is executed\n' | |
| 4378 '(and no other part of the "if" statement is executed or evaluated).\n' | |
| 4379 'If all expressions are false, the suite of the "else" clause, if\n' | |
| 4380 'present, is executed.\n', | |
| 4381 'exceptions': 'Exceptions\n' | |
| 4382 '**********\n' | |
| 4383 '\n' | |
| 4384 'Exceptions are a means of breaking out of the normal flow of ' | |
| 4385 'control\n' | |
| 4386 'of a code block in order to handle errors or other ' | |
| 4387 'exceptional\n' | |
| 4388 'conditions. An exception is *raised* at the point where the ' | |
| 4389 'error is\n' | |
| 4390 'detected; it may be *handled* by the surrounding code block or ' | |
| 4391 'by any\n' | |
| 4392 'code block that directly or indirectly invoked the code block ' | |
| 4393 'where\n' | |
| 4394 'the error occurred.\n' | |
| 4395 '\n' | |
| 4396 'The Python interpreter raises an exception when it detects a ' | |
| 4397 'run-time\n' | |
| 4398 'error (such as division by zero). A Python program can also\n' | |
| 4399 'explicitly raise an exception with the "raise" statement. ' | |
| 4400 'Exception\n' | |
| 4401 'handlers are specified with the "try" … "except" statement. ' | |
| 4402 'The\n' | |
| 4403 '"finally" clause of such a statement can be used to specify ' | |
| 4404 'cleanup\n' | |
| 4405 'code which does not handle the exception, but is executed ' | |
| 4406 'whether an\n' | |
| 4407 'exception occurred or not in the preceding code.\n' | |
| 4408 '\n' | |
| 4409 'Python uses the “termination” model of error handling: an ' | |
| 4410 'exception\n' | |
| 4411 'handler can find out what happened and continue execution at ' | |
| 4412 'an outer\n' | |
| 4413 'level, but it cannot repair the cause of the error and retry ' | |
| 4414 'the\n' | |
| 4415 'failing operation (except by re-entering the offending piece ' | |
| 4416 'of code\n' | |
| 4417 'from the top).\n' | |
| 4418 '\n' | |
| 4419 'When an exception is not handled at all, the interpreter ' | |
| 4420 'terminates\n' | |
| 4421 'execution of the program, or returns to its interactive main ' | |
| 4422 'loop. In\n' | |
| 4423 'either case, it prints a stack traceback, except when the ' | |
| 4424 'exception is\n' | |
| 4425 '"SystemExit".\n' | |
| 4426 '\n' | |
| 4427 'Exceptions are identified by class instances. The "except" ' | |
| 4428 'clause is\n' | |
| 4429 'selected depending on the class of the instance: it must ' | |
| 4430 'reference the\n' | |
| 4431 'class of the instance or a base class thereof. The instance ' | |
| 4432 'can be\n' | |
| 4433 'received by the handler and can carry additional information ' | |
| 4434 'about the\n' | |
| 4435 'exceptional condition.\n' | |
| 4436 '\n' | |
| 4437 'Note: Exception messages are not part of the Python API. ' | |
| 4438 'Their\n' | |
| 4439 ' contents may change from one version of Python to the next ' | |
| 4440 'without\n' | |
| 4441 ' warning and should not be relied on by code which will run ' | |
| 4442 'under\n' | |
| 4443 ' multiple versions of the interpreter.\n' | |
| 4444 '\n' | |
| 4445 'See also the description of the "try" statement in section The ' | |
| 4446 'try\n' | |
| 4447 'statement and "raise" statement in section The raise ' | |
| 4448 'statement.\n' | |
| 4449 '\n' | |
| 4450 '-[ Footnotes ]-\n' | |
| 4451 '\n' | |
| 4452 '[1] This limitation occurs because the code that is executed ' | |
| 4453 'by\n' | |
| 4454 ' these operations is not available at the time the module ' | |
| 4455 'is\n' | |
| 4456 ' compiled.\n', | |
| 4457 'execmodel': 'Execution model\n' | |
| 4458 '***************\n' | |
| 4459 '\n' | |
| 4460 '\n' | |
| 4461 'Structure of a program\n' | |
| 4462 '======================\n' | |
| 4463 '\n' | |
| 4464 'A Python program is constructed from code blocks. A *block* is ' | |
| 4465 'a piece\n' | |
| 4466 'of Python program text that is executed as a unit. The ' | |
| 4467 'following are\n' | |
| 4468 'blocks: a module, a function body, and a class definition. ' | |
| 4469 'Each\n' | |
| 4470 'command typed interactively is a block. A script file (a file ' | |
| 4471 'given\n' | |
| 4472 'as standard input to the interpreter or specified as a command ' | |
| 4473 'line\n' | |
| 4474 'argument to the interpreter) is a code block. A script command ' | |
| 4475 '(a\n' | |
| 4476 'command specified on the interpreter command line with the ' | |
| 4477 '"-c"\n' | |
| 4478 'option) is a code block. The string argument passed to the ' | |
| 4479 'built-in\n' | |
| 4480 'functions "eval()" and "exec()" is a code block.\n' | |
| 4481 '\n' | |
| 4482 'A code block is executed in an *execution frame*. A frame ' | |
| 4483 'contains\n' | |
| 4484 'some administrative information (used for debugging) and ' | |
| 4485 'determines\n' | |
| 4486 'where and how execution continues after the code block’s ' | |
| 4487 'execution has\n' | |
| 4488 'completed.\n' | |
| 4489 '\n' | |
| 4490 '\n' | |
| 4491 'Naming and binding\n' | |
| 4492 '==================\n' | |
| 4493 '\n' | |
| 4494 '\n' | |
| 4495 'Binding of names\n' | |
| 4496 '----------------\n' | |
| 4497 '\n' | |
| 4498 '*Names* refer to objects. Names are introduced by name ' | |
| 4499 'binding\n' | |
| 4500 'operations.\n' | |
| 4501 '\n' | |
| 4502 'The following constructs bind names: formal parameters to ' | |
| 4503 'functions,\n' | |
| 4504 '"import" statements, class and function definitions (these bind ' | |
| 4505 'the\n' | |
| 4506 'class or function name in the defining block), and targets that ' | |
| 4507 'are\n' | |
| 4508 'identifiers if occurring in an assignment, "for" loop header, ' | |
| 4509 'or after\n' | |
| 4510 '"as" in a "with" statement or "except" clause. The "import" ' | |
| 4511 'statement\n' | |
| 4512 'of the form "from ... import *" binds all names defined in the\n' | |
| 4513 'imported module, except those beginning with an underscore. ' | |
| 4514 'This form\n' | |
| 4515 'may only be used at the module level.\n' | |
| 4516 '\n' | |
| 4517 'A target occurring in a "del" statement is also considered ' | |
| 4518 'bound for\n' | |
| 4519 'this purpose (though the actual semantics are to unbind the ' | |
| 4520 'name).\n' | |
| 4521 '\n' | |
| 4522 'Each assignment or import statement occurs within a block ' | |
| 4523 'defined by a\n' | |
| 4524 'class or function definition or at the module level (the ' | |
| 4525 'top-level\n' | |
| 4526 'code block).\n' | |
| 4527 '\n' | |
| 4528 'If a name is bound in a block, it is a local variable of that ' | |
| 4529 'block,\n' | |
| 4530 'unless declared as "nonlocal" or "global". If a name is bound ' | |
| 4531 'at the\n' | |
| 4532 'module level, it is a global variable. (The variables of the ' | |
| 4533 'module\n' | |
| 4534 'code block are local and global.) If a variable is used in a ' | |
| 4535 'code\n' | |
| 4536 'block but not defined there, it is a *free variable*.\n' | |
| 4537 '\n' | |
| 4538 'Each occurrence of a name in the program text refers to the ' | |
| 4539 '*binding*\n' | |
| 4540 'of that name established by the following name resolution ' | |
| 4541 'rules.\n' | |
| 4542 '\n' | |
| 4543 '\n' | |
| 4544 'Resolution of names\n' | |
| 4545 '-------------------\n' | |
| 4546 '\n' | |
| 4547 'A *scope* defines the visibility of a name within a block. If ' | |
| 4548 'a local\n' | |
| 4549 'variable is defined in a block, its scope includes that block. ' | |
| 4550 'If the\n' | |
| 4551 'definition occurs in a function block, the scope extends to any ' | |
| 4552 'blocks\n' | |
| 4553 'contained within the defining one, unless a contained block ' | |
| 4554 'introduces\n' | |
| 4555 'a different binding for the name.\n' | |
| 4556 '\n' | |
| 4557 'When a name is used in a code block, it is resolved using the ' | |
| 4558 'nearest\n' | |
| 4559 'enclosing scope. The set of all such scopes visible to a code ' | |
| 4560 'block\n' | |
| 4561 'is called the block’s *environment*.\n' | |
| 4562 '\n' | |
| 4563 'When a name is not found at all, a "NameError" exception is ' | |
| 4564 'raised. If\n' | |
| 4565 'the current scope is a function scope, and the name refers to a ' | |
| 4566 'local\n' | |
| 4567 'variable that has not yet been bound to a value at the point ' | |
| 4568 'where the\n' | |
| 4569 'name is used, an "UnboundLocalError" exception is raised.\n' | |
| 4570 '"UnboundLocalError" is a subclass of "NameError".\n' | |
| 4571 '\n' | |
| 4572 'If a name binding operation occurs anywhere within a code ' | |
| 4573 'block, all\n' | |
| 4574 'uses of the name within the block are treated as references to ' | |
| 4575 'the\n' | |
| 4576 'current block. This can lead to errors when a name is used ' | |
| 4577 'within a\n' | |
| 4578 'block before it is bound. This rule is subtle. Python lacks\n' | |
| 4579 'declarations and allows name binding operations to occur ' | |
| 4580 'anywhere\n' | |
| 4581 'within a code block. The local variables of a code block can ' | |
| 4582 'be\n' | |
| 4583 'determined by scanning the entire text of the block for name ' | |
| 4584 'binding\n' | |
| 4585 'operations.\n' | |
| 4586 '\n' | |
| 4587 'If the "global" statement occurs within a block, all uses of ' | |
| 4588 'the name\n' | |
| 4589 'specified in the statement refer to the binding of that name in ' | |
| 4590 'the\n' | |
| 4591 'top-level namespace. Names are resolved in the top-level ' | |
| 4592 'namespace by\n' | |
| 4593 'searching the global namespace, i.e. the namespace of the ' | |
| 4594 'module\n' | |
| 4595 'containing the code block, and the builtins namespace, the ' | |
| 4596 'namespace\n' | |
| 4597 'of the module "builtins". The global namespace is searched ' | |
| 4598 'first. If\n' | |
| 4599 'the name is not found there, the builtins namespace is ' | |
| 4600 'searched. The\n' | |
| 4601 '"global" statement must precede all uses of the name.\n' | |
| 4602 '\n' | |
| 4603 'The "global" statement has the same scope as a name binding ' | |
| 4604 'operation\n' | |
| 4605 'in the same block. If the nearest enclosing scope for a free ' | |
| 4606 'variable\n' | |
| 4607 'contains a global statement, the free variable is treated as a ' | |
| 4608 'global.\n' | |
| 4609 '\n' | |
| 4610 'The "nonlocal" statement causes corresponding names to refer ' | |
| 4611 'to\n' | |
| 4612 'previously bound variables in the nearest enclosing function ' | |
| 4613 'scope.\n' | |
| 4614 '"SyntaxError" is raised at compile time if the given name does ' | |
| 4615 'not\n' | |
| 4616 'exist in any enclosing function scope.\n' | |
| 4617 '\n' | |
| 4618 'The namespace for a module is automatically created the first ' | |
| 4619 'time a\n' | |
| 4620 'module is imported. The main module for a script is always ' | |
| 4621 'called\n' | |
| 4622 '"__main__".\n' | |
| 4623 '\n' | |
| 4624 'Class definition blocks and arguments to "exec()" and "eval()" ' | |
| 4625 'are\n' | |
| 4626 'special in the context of name resolution. A class definition ' | |
| 4627 'is an\n' | |
| 4628 'executable statement that may use and define names. These ' | |
| 4629 'references\n' | |
| 4630 'follow the normal rules for name resolution with an exception ' | |
| 4631 'that\n' | |
| 4632 'unbound local variables are looked up in the global namespace. ' | |
| 4633 'The\n' | |
| 4634 'namespace of the class definition becomes the attribute ' | |
| 4635 'dictionary of\n' | |
| 4636 'the class. The scope of names defined in a class block is ' | |
| 4637 'limited to\n' | |
| 4638 'the class block; it does not extend to the code blocks of ' | |
| 4639 'methods –\n' | |
| 4640 'this includes comprehensions and generator expressions since ' | |
| 4641 'they are\n' | |
| 4642 'implemented using a function scope. This means that the ' | |
| 4643 'following\n' | |
| 4644 'will fail:\n' | |
| 4645 '\n' | |
| 4646 ' class A:\n' | |
| 4647 ' a = 42\n' | |
| 4648 ' b = list(a + i for i in range(10))\n' | |
| 4649 '\n' | |
| 4650 '\n' | |
| 4651 'Builtins and restricted execution\n' | |
| 4652 '---------------------------------\n' | |
| 4653 '\n' | |
| 4654 '**CPython implementation detail:** Users should not touch\n' | |
| 4655 '"__builtins__"; it is strictly an implementation detail. ' | |
| 4656 'Users\n' | |
| 4657 'wanting to override values in the builtins namespace should ' | |
| 4658 '"import"\n' | |
| 4659 'the "builtins" module and modify its attributes appropriately.\n' | |
| 4660 '\n' | |
| 4661 'The builtins namespace associated with the execution of a code ' | |
| 4662 'block\n' | |
| 4663 'is actually found by looking up the name "__builtins__" in its ' | |
| 4664 'global\n' | |
| 4665 'namespace; this should be a dictionary or a module (in the ' | |
| 4666 'latter case\n' | |
| 4667 'the module’s dictionary is used). By default, when in the ' | |
| 4668 '"__main__"\n' | |
| 4669 'module, "__builtins__" is the built-in module "builtins"; when ' | |
| 4670 'in any\n' | |
| 4671 'other module, "__builtins__" is an alias for the dictionary of ' | |
| 4672 'the\n' | |
| 4673 '"builtins" module itself.\n' | |
| 4674 '\n' | |
| 4675 '\n' | |
| 4676 'Interaction with dynamic features\n' | |
| 4677 '---------------------------------\n' | |
| 4678 '\n' | |
| 4679 'Name resolution of free variables occurs at runtime, not at ' | |
| 4680 'compile\n' | |
| 4681 'time. This means that the following code will print 42:\n' | |
| 4682 '\n' | |
| 4683 ' i = 10\n' | |
| 4684 ' def f():\n' | |
| 4685 ' print(i)\n' | |
| 4686 ' i = 42\n' | |
| 4687 ' f()\n' | |
| 4688 '\n' | |
| 4689 'The "eval()" and "exec()" functions do not have access to the ' | |
| 4690 'full\n' | |
| 4691 'environment for resolving names. Names may be resolved in the ' | |
| 4692 'local\n' | |
| 4693 'and global namespaces of the caller. Free variables are not ' | |
| 4694 'resolved\n' | |
| 4695 'in the nearest enclosing namespace, but in the global ' | |
| 4696 'namespace. [1]\n' | |
| 4697 'The "exec()" and "eval()" functions have optional arguments to\n' | |
| 4698 'override the global and local namespace. If only one namespace ' | |
| 4699 'is\n' | |
| 4700 'specified, it is used for both.\n' | |
| 4701 '\n' | |
| 4702 '\n' | |
| 4703 'Exceptions\n' | |
| 4704 '==========\n' | |
| 4705 '\n' | |
| 4706 'Exceptions are a means of breaking out of the normal flow of ' | |
| 4707 'control\n' | |
| 4708 'of a code block in order to handle errors or other exceptional\n' | |
| 4709 'conditions. An exception is *raised* at the point where the ' | |
| 4710 'error is\n' | |
| 4711 'detected; it may be *handled* by the surrounding code block or ' | |
| 4712 'by any\n' | |
| 4713 'code block that directly or indirectly invoked the code block ' | |
| 4714 'where\n' | |
| 4715 'the error occurred.\n' | |
| 4716 '\n' | |
| 4717 'The Python interpreter raises an exception when it detects a ' | |
| 4718 'run-time\n' | |
| 4719 'error (such as division by zero). A Python program can also\n' | |
| 4720 'explicitly raise an exception with the "raise" statement. ' | |
| 4721 'Exception\n' | |
| 4722 'handlers are specified with the "try" … "except" statement. ' | |
| 4723 'The\n' | |
| 4724 '"finally" clause of such a statement can be used to specify ' | |
| 4725 'cleanup\n' | |
| 4726 'code which does not handle the exception, but is executed ' | |
| 4727 'whether an\n' | |
| 4728 'exception occurred or not in the preceding code.\n' | |
| 4729 '\n' | |
| 4730 'Python uses the “termination” model of error handling: an ' | |
| 4731 'exception\n' | |
| 4732 'handler can find out what happened and continue execution at an ' | |
| 4733 'outer\n' | |
| 4734 'level, but it cannot repair the cause of the error and retry ' | |
| 4735 'the\n' | |
| 4736 'failing operation (except by re-entering the offending piece of ' | |
| 4737 'code\n' | |
| 4738 'from the top).\n' | |
| 4739 '\n' | |
| 4740 'When an exception is not handled at all, the interpreter ' | |
| 4741 'terminates\n' | |
| 4742 'execution of the program, or returns to its interactive main ' | |
| 4743 'loop. In\n' | |
| 4744 'either case, it prints a stack traceback, except when the ' | |
| 4745 'exception is\n' | |
| 4746 '"SystemExit".\n' | |
| 4747 '\n' | |
| 4748 'Exceptions are identified by class instances. The "except" ' | |
| 4749 'clause is\n' | |
| 4750 'selected depending on the class of the instance: it must ' | |
| 4751 'reference the\n' | |
| 4752 'class of the instance or a base class thereof. The instance ' | |
| 4753 'can be\n' | |
| 4754 'received by the handler and can carry additional information ' | |
| 4755 'about the\n' | |
| 4756 'exceptional condition.\n' | |
| 4757 '\n' | |
| 4758 'Note: Exception messages are not part of the Python API. ' | |
| 4759 'Their\n' | |
| 4760 ' contents may change from one version of Python to the next ' | |
| 4761 'without\n' | |
| 4762 ' warning and should not be relied on by code which will run ' | |
| 4763 'under\n' | |
| 4764 ' multiple versions of the interpreter.\n' | |
| 4765 '\n' | |
| 4766 'See also the description of the "try" statement in section The ' | |
| 4767 'try\n' | |
| 4768 'statement and "raise" statement in section The raise ' | |
| 4769 'statement.\n' | |
| 4770 '\n' | |
| 4771 '-[ Footnotes ]-\n' | |
| 4772 '\n' | |
| 4773 '[1] This limitation occurs because the code that is executed ' | |
| 4774 'by\n' | |
| 4775 ' these operations is not available at the time the module ' | |
| 4776 'is\n' | |
| 4777 ' compiled.\n', | |
| 4778 'exprlists': 'Expression lists\n' | |
| 4779 '****************\n' | |
| 4780 '\n' | |
| 4781 ' expression_list ::= expression ("," expression)* [","]\n' | |
| 4782 ' starred_list ::= starred_item ("," starred_item)* ' | |
| 4783 '[","]\n' | |
| 4784 ' starred_expression ::= expression | (starred_item ",")* ' | |
| 4785 '[starred_item]\n' | |
| 4786 ' starred_item ::= expression | "*" or_expr\n' | |
| 4787 '\n' | |
| 4788 'Except when part of a list or set display, an expression list\n' | |
| 4789 'containing at least one comma yields a tuple. The length of ' | |
| 4790 'the tuple\n' | |
| 4791 'is the number of expressions in the list. The expressions are\n' | |
| 4792 'evaluated from left to right.\n' | |
| 4793 '\n' | |
| 4794 'An asterisk "*" denotes *iterable unpacking*. Its operand must ' | |
| 4795 'be an\n' | |
| 4796 '*iterable*. The iterable is expanded into a sequence of items, ' | |
| 4797 'which\n' | |
| 4798 'are included in the new tuple, list, or set, at the site of ' | |
| 4799 'the\n' | |
| 4800 'unpacking.\n' | |
| 4801 '\n' | |
| 4802 'New in version 3.5: Iterable unpacking in expression lists, ' | |
| 4803 'originally\n' | |
| 4804 'proposed by **PEP 448**.\n' | |
| 4805 '\n' | |
| 4806 'The trailing comma is required only to create a single tuple ' | |
| 4807 '(a.k.a. a\n' | |
| 4808 '*singleton*); it is optional in all other cases. A single ' | |
| 4809 'expression\n' | |
| 4810 'without a trailing comma doesn’t create a tuple, but rather ' | |
| 4811 'yields the\n' | |
| 4812 'value of that expression. (To create an empty tuple, use an ' | |
| 4813 'empty pair\n' | |
| 4814 'of parentheses: "()".)\n', | |
| 4815 'floating': 'Floating point literals\n' | |
| 4816 '***********************\n' | |
| 4817 '\n' | |
| 4818 'Floating point literals are described by the following lexical\n' | |
| 4819 'definitions:\n' | |
| 4820 '\n' | |
| 4821 ' floatnumber ::= pointfloat | exponentfloat\n' | |
| 4822 ' pointfloat ::= [digitpart] fraction | digitpart "."\n' | |
| 4823 ' exponentfloat ::= (digitpart | pointfloat) exponent\n' | |
| 4824 ' digitpart ::= digit (["_"] digit)*\n' | |
| 4825 ' fraction ::= "." digitpart\n' | |
| 4826 ' exponent ::= ("e" | "E") ["+" | "-"] digitpart\n' | |
| 4827 '\n' | |
| 4828 'Note that the integer and exponent parts are always interpreted ' | |
| 4829 'using\n' | |
| 4830 'radix 10. For example, "077e010" is legal, and denotes the same ' | |
| 4831 'number\n' | |
| 4832 'as "77e10". The allowed range of floating point literals is\n' | |
| 4833 'implementation-dependent. As in integer literals, underscores ' | |
| 4834 'are\n' | |
| 4835 'supported for digit grouping.\n' | |
| 4836 '\n' | |
| 4837 'Some examples of floating point literals:\n' | |
| 4838 '\n' | |
| 4839 ' 3.14 10. .001 1e100 3.14e-10 0e0 ' | |
| 4840 '3.14_15_93\n' | |
| 4841 '\n' | |
| 4842 'Changed in version 3.6: Underscores are now allowed for ' | |
| 4843 'grouping\n' | |
| 4844 'purposes in literals.\n', | |
| 4845 'for': 'The "for" statement\n' | |
| 4846 '*******************\n' | |
| 4847 '\n' | |
| 4848 'The "for" statement is used to iterate over the elements of a ' | |
| 4849 'sequence\n' | |
| 4850 '(such as a string, tuple or list) or other iterable object:\n' | |
| 4851 '\n' | |
| 4852 ' for_stmt ::= "for" target_list "in" expression_list ":" suite\n' | |
| 4853 ' ["else" ":" suite]\n' | |
| 4854 '\n' | |
| 4855 'The expression list is evaluated once; it should yield an iterable\n' | |
| 4856 'object. An iterator is created for the result of the\n' | |
| 4857 '"expression_list". The suite is then executed once for each item\n' | |
| 4858 'provided by the iterator, in the order returned by the iterator. ' | |
| 4859 'Each\n' | |
| 4860 'item in turn is assigned to the target list using the standard rules\n' | |
| 4861 'for assignments (see Assignment statements), and then the suite is\n' | |
| 4862 'executed. When the items are exhausted (which is immediately when ' | |
| 4863 'the\n' | |
| 4864 'sequence is empty or an iterator raises a "StopIteration" ' | |
| 4865 'exception),\n' | |
| 4866 'the suite in the "else" clause, if present, is executed, and the ' | |
| 4867 'loop\n' | |
| 4868 'terminates.\n' | |
| 4869 '\n' | |
| 4870 'A "break" statement executed in the first suite terminates the loop\n' | |
| 4871 'without executing the "else" clause’s suite. A "continue" statement\n' | |
| 4872 'executed in the first suite skips the rest of the suite and ' | |
| 4873 'continues\n' | |
| 4874 'with the next item, or with the "else" clause if there is no next\n' | |
| 4875 'item.\n' | |
| 4876 '\n' | |
| 4877 'The for-loop makes assignments to the variables in the target list.\n' | |
| 4878 'This overwrites all previous assignments to those variables ' | |
| 4879 'including\n' | |
| 4880 'those made in the suite of the for-loop:\n' | |
| 4881 '\n' | |
| 4882 ' for i in range(10):\n' | |
| 4883 ' print(i)\n' | |
| 4884 ' i = 5 # this will not affect the for-loop\n' | |
| 4885 ' # because i will be overwritten with the ' | |
| 4886 'next\n' | |
| 4887 ' # index in the range\n' | |
| 4888 '\n' | |
| 4889 'Names in the target list are not deleted when the loop is finished,\n' | |
| 4890 'but if the sequence is empty, they will not have been assigned to at\n' | |
| 4891 'all by the loop. Hint: the built-in function "range()" returns an\n' | |
| 4892 'iterator of integers suitable to emulate the effect of Pascal’s "for ' | |
| 4893 'i\n' | |
| 4894 ':= a to b do"; e.g., "list(range(3))" returns the list "[0, 1, 2]".\n' | |
| 4895 '\n' | |
| 4896 'Note: There is a subtlety when the sequence is being modified by the\n' | |
| 4897 ' loop (this can only occur for mutable sequences, e.g. lists). An\n' | |
| 4898 ' internal counter is used to keep track of which item is used next,\n' | |
| 4899 ' and this is incremented on each iteration. When this counter has\n' | |
| 4900 ' reached the length of the sequence the loop terminates. This ' | |
| 4901 'means\n' | |
| 4902 ' that if the suite deletes the current (or a previous) item from ' | |
| 4903 'the\n' | |
| 4904 ' sequence, the next item will be skipped (since it gets the index ' | |
| 4905 'of\n' | |
| 4906 ' the current item which has already been treated). Likewise, if ' | |
| 4907 'the\n' | |
| 4908 ' suite inserts an item in the sequence before the current item, the\n' | |
| 4909 ' current item will be treated again the next time through the loop.\n' | |
| 4910 ' This can lead to nasty bugs that can be avoided by making a\n' | |
| 4911 ' temporary copy using a slice of the whole sequence, e.g.,\n' | |
| 4912 '\n' | |
| 4913 ' for x in a[:]:\n' | |
| 4914 ' if x < 0: a.remove(x)\n', | |
| 4915 'formatstrings': 'Format String Syntax\n' | |
| 4916 '********************\n' | |
| 4917 '\n' | |
| 4918 'The "str.format()" method and the "Formatter" class share ' | |
| 4919 'the same\n' | |
| 4920 'syntax for format strings (although in the case of ' | |
| 4921 '"Formatter",\n' | |
| 4922 'subclasses can define their own format string syntax). The ' | |
| 4923 'syntax is\n' | |
| 4924 'related to that of formatted string literals, but there ' | |
| 4925 'are\n' | |
| 4926 'differences.\n' | |
| 4927 '\n' | |
| 4928 'Format strings contain “replacement fields” surrounded by ' | |
| 4929 'curly braces\n' | |
| 4930 '"{}". Anything that is not contained in braces is ' | |
| 4931 'considered literal\n' | |
| 4932 'text, which is copied unchanged to the output. If you need ' | |
| 4933 'to include\n' | |
| 4934 'a brace character in the literal text, it can be escaped by ' | |
| 4935 'doubling:\n' | |
| 4936 '"{{" and "}}".\n' | |
| 4937 '\n' | |
| 4938 'The grammar for a replacement field is as follows:\n' | |
| 4939 '\n' | |
| 4940 ' replacement_field ::= "{" [field_name] ["!" ' | |
| 4941 'conversion] [":" format_spec] "}"\n' | |
| 4942 ' field_name ::= arg_name ("." attribute_name | ' | |
| 4943 '"[" element_index "]")*\n' | |
| 4944 ' arg_name ::= [identifier | digit+]\n' | |
| 4945 ' attribute_name ::= identifier\n' | |
| 4946 ' element_index ::= digit+ | index_string\n' | |
| 4947 ' index_string ::= <any source character except ' | |
| 4948 '"]"> +\n' | |
| 4949 ' conversion ::= "r" | "s" | "a"\n' | |
| 4950 ' format_spec ::= <described in the next ' | |
| 4951 'section>\n' | |
| 4952 '\n' | |
| 4953 'In less formal terms, the replacement field can start with ' | |
| 4954 'a\n' | |
| 4955 '*field_name* that specifies the object whose value is to be ' | |
| 4956 'formatted\n' | |
| 4957 'and inserted into the output instead of the replacement ' | |
| 4958 'field. The\n' | |
| 4959 '*field_name* is optionally followed by a *conversion* ' | |
| 4960 'field, which is\n' | |
| 4961 'preceded by an exclamation point "\'!\'", and a ' | |
| 4962 '*format_spec*, which is\n' | |
| 4963 'preceded by a colon "\':\'". These specify a non-default ' | |
| 4964 'format for the\n' | |
| 4965 'replacement value.\n' | |
| 4966 '\n' | |
| 4967 'See also the Format Specification Mini-Language section.\n' | |
| 4968 '\n' | |
| 4969 'The *field_name* itself begins with an *arg_name* that is ' | |
| 4970 'either a\n' | |
| 4971 'number or a keyword. If it’s a number, it refers to a ' | |
| 4972 'positional\n' | |
| 4973 'argument, and if it’s a keyword, it refers to a named ' | |
| 4974 'keyword\n' | |
| 4975 'argument. If the numerical arg_names in a format string ' | |
| 4976 'are 0, 1, 2,\n' | |
| 4977 '… in sequence, they can all be omitted (not just some) and ' | |
| 4978 'the numbers\n' | |
| 4979 '0, 1, 2, … will be automatically inserted in that order. ' | |
| 4980 'Because\n' | |
| 4981 '*arg_name* is not quote-delimited, it is not possible to ' | |
| 4982 'specify\n' | |
| 4983 'arbitrary dictionary keys (e.g., the strings "\'10\'" or ' | |
| 4984 '"\':-]\'") within\n' | |
| 4985 'a format string. The *arg_name* can be followed by any ' | |
| 4986 'number of index\n' | |
| 4987 'or attribute expressions. An expression of the form ' | |
| 4988 '"\'.name\'" selects\n' | |
| 4989 'the named attribute using "getattr()", while an expression ' | |
| 4990 'of the form\n' | |
| 4991 '"\'[index]\'" does an index lookup using "__getitem__()".\n' | |
| 4992 '\n' | |
| 4993 'Changed in version 3.1: The positional argument specifiers ' | |
| 4994 'can be\n' | |
| 4995 'omitted for "str.format()", so "\'{} {}\'.format(a, b)" is ' | |
| 4996 'equivalent to\n' | |
| 4997 '"\'{0} {1}\'.format(a, b)".\n' | |
| 4998 '\n' | |
| 4999 'Changed in version 3.4: The positional argument specifiers ' | |
| 5000 'can be\n' | |
| 5001 'omitted for "Formatter".\n' | |
| 5002 '\n' | |
| 5003 'Some simple format string examples:\n' | |
| 5004 '\n' | |
| 5005 ' "First, thou shalt count to {0}" # References first ' | |
| 5006 'positional argument\n' | |
| 5007 ' "Bring me a {}" # Implicitly ' | |
| 5008 'references the first positional argument\n' | |
| 5009 ' "From {} to {}" # Same as "From {0} to ' | |
| 5010 '{1}"\n' | |
| 5011 ' "My quest is {name}" # References keyword ' | |
| 5012 "argument 'name'\n" | |
| 5013 ' "Weight in tons {0.weight}" # \'weight\' attribute ' | |
| 5014 'of first positional arg\n' | |
| 5015 ' "Units destroyed: {players[0]}" # First element of ' | |
| 5016 "keyword argument 'players'.\n" | |
| 5017 '\n' | |
| 5018 'The *conversion* field causes a type coercion before ' | |
| 5019 'formatting.\n' | |
| 5020 'Normally, the job of formatting a value is done by the ' | |
| 5021 '"__format__()"\n' | |
| 5022 'method of the value itself. However, in some cases it is ' | |
| 5023 'desirable to\n' | |
| 5024 'force a type to be formatted as a string, overriding its ' | |
| 5025 'own\n' | |
| 5026 'definition of formatting. By converting the value to a ' | |
| 5027 'string before\n' | |
| 5028 'calling "__format__()", the normal formatting logic is ' | |
| 5029 'bypassed.\n' | |
| 5030 '\n' | |
| 5031 'Three conversion flags are currently supported: "\'!s\'" ' | |
| 5032 'which calls\n' | |
| 5033 '"str()" on the value, "\'!r\'" which calls "repr()" and ' | |
| 5034 '"\'!a\'" which\n' | |
| 5035 'calls "ascii()".\n' | |
| 5036 '\n' | |
| 5037 'Some examples:\n' | |
| 5038 '\n' | |
| 5039 ' "Harold\'s a clever {0!s}" # Calls str() on the ' | |
| 5040 'argument first\n' | |
| 5041 ' "Bring out the holy {name!r}" # Calls repr() on the ' | |
| 5042 'argument first\n' | |
| 5043 ' "More {!a}" # Calls ascii() on the ' | |
| 5044 'argument first\n' | |
| 5045 '\n' | |
| 5046 'The *format_spec* field contains a specification of how the ' | |
| 5047 'value\n' | |
| 5048 'should be presented, including such details as field width, ' | |
| 5049 'alignment,\n' | |
| 5050 'padding, decimal precision and so on. Each value type can ' | |
| 5051 'define its\n' | |
| 5052 'own “formatting mini-language” or interpretation of the ' | |
| 5053 '*format_spec*.\n' | |
| 5054 '\n' | |
| 5055 'Most built-in types support a common formatting ' | |
| 5056 'mini-language, which\n' | |
| 5057 'is described in the next section.\n' | |
| 5058 '\n' | |
| 5059 'A *format_spec* field can also include nested replacement ' | |
| 5060 'fields\n' | |
| 5061 'within it. These nested replacement fields may contain a ' | |
| 5062 'field name,\n' | |
| 5063 'conversion flag and format specification, but deeper ' | |
| 5064 'nesting is not\n' | |
| 5065 'allowed. The replacement fields within the format_spec ' | |
| 5066 'are\n' | |
| 5067 'substituted before the *format_spec* string is interpreted. ' | |
| 5068 'This\n' | |
| 5069 'allows the formatting of a value to be dynamically ' | |
| 5070 'specified.\n' | |
| 5071 '\n' | |
| 5072 'See the Format examples section for some examples.\n' | |
| 5073 '\n' | |
| 5074 '\n' | |
| 5075 'Format Specification Mini-Language\n' | |
| 5076 '==================================\n' | |
| 5077 '\n' | |
| 5078 '“Format specifications” are used within replacement fields ' | |
| 5079 'contained\n' | |
| 5080 'within a format string to define how individual values are ' | |
| 5081 'presented\n' | |
| 5082 '(see Format String Syntax and Formatted string literals). ' | |
| 5083 'They can\n' | |
| 5084 'also be passed directly to the built-in "format()" ' | |
| 5085 'function. Each\n' | |
| 5086 'formattable type may define how the format specification is ' | |
| 5087 'to be\n' | |
| 5088 'interpreted.\n' | |
| 5089 '\n' | |
| 5090 'Most built-in types implement the following options for ' | |
| 5091 'format\n' | |
| 5092 'specifications, although some of the formatting options are ' | |
| 5093 'only\n' | |
| 5094 'supported by the numeric types.\n' | |
| 5095 '\n' | |
| 5096 'A general convention is that an empty format string ("""") ' | |
| 5097 'produces\n' | |
| 5098 'the same result as if you had called "str()" on the value. ' | |
| 5099 'A non-empty\n' | |
| 5100 'format string typically modifies the result.\n' | |
| 5101 '\n' | |
| 5102 'The general form of a *standard format specifier* is:\n' | |
| 5103 '\n' | |
| 5104 ' format_spec ::= ' | |
| 5105 '[[fill]align][sign][#][0][width][grouping_option][.precision][type]\n' | |
| 5106 ' fill ::= <any character>\n' | |
| 5107 ' align ::= "<" | ">" | "=" | "^"\n' | |
| 5108 ' sign ::= "+" | "-" | " "\n' | |
| 5109 ' width ::= digit+\n' | |
| 5110 ' grouping_option ::= "_" | ","\n' | |
| 5111 ' precision ::= digit+\n' | |
| 5112 ' type ::= "b" | "c" | "d" | "e" | "E" | "f" | ' | |
| 5113 '"F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"\n' | |
| 5114 '\n' | |
| 5115 'If a valid *align* value is specified, it can be preceded ' | |
| 5116 'by a *fill*\n' | |
| 5117 'character that can be any character and defaults to a space ' | |
| 5118 'if\n' | |
| 5119 'omitted. It is not possible to use a literal curly brace ' | |
| 5120 '(“"{"” or\n' | |
| 5121 '“"}"”) as the *fill* character in a formatted string ' | |
| 5122 'literal or when\n' | |
| 5123 'using the "str.format()" method. However, it is possible ' | |
| 5124 'to insert a\n' | |
| 5125 'curly brace with a nested replacement field. This ' | |
| 5126 'limitation doesn’t\n' | |
| 5127 'affect the "format()" function.\n' | |
| 5128 '\n' | |
| 5129 'The meaning of the various alignment options is as ' | |
| 5130 'follows:\n' | |
| 5131 '\n' | |
| 5132 ' ' | |
| 5133 '+-----------+------------------------------------------------------------+\n' | |
| 5134 ' | Option | ' | |
| 5135 'Meaning ' | |
| 5136 '|\n' | |
| 5137 ' ' | |
| 5138 '|===========|============================================================|\n' | |
| 5139 ' | "\'<\'" | Forces the field to be left-aligned ' | |
| 5140 'within the available |\n' | |
| 5141 ' | | space (this is the default for most ' | |
| 5142 'objects). |\n' | |
| 5143 ' ' | |
| 5144 '+-----------+------------------------------------------------------------+\n' | |
| 5145 ' | "\'>\'" | Forces the field to be right-aligned ' | |
| 5146 'within the available |\n' | |
| 5147 ' | | space (this is the default for ' | |
| 5148 'numbers). |\n' | |
| 5149 ' ' | |
| 5150 '+-----------+------------------------------------------------------------+\n' | |
| 5151 ' | "\'=\'" | Forces the padding to be placed after ' | |
| 5152 'the sign (if any) |\n' | |
| 5153 ' | | but before the digits. This is used for ' | |
| 5154 'printing fields |\n' | |
| 5155 ' | | in the form ‘+000000120’. This alignment ' | |
| 5156 'option is only |\n' | |
| 5157 ' | | valid for numeric types. It becomes the ' | |
| 5158 'default when ‘0’ |\n' | |
| 5159 ' | | immediately precedes the field ' | |
| 5160 'width. |\n' | |
| 5161 ' ' | |
| 5162 '+-----------+------------------------------------------------------------+\n' | |
| 5163 ' | "\'^\'" | Forces the field to be centered within ' | |
| 5164 'the available |\n' | |
| 5165 ' | | ' | |
| 5166 'space. ' | |
| 5167 '|\n' | |
| 5168 ' ' | |
| 5169 '+-----------+------------------------------------------------------------+\n' | |
| 5170 '\n' | |
| 5171 'Note that unless a minimum field width is defined, the ' | |
| 5172 'field width\n' | |
| 5173 'will always be the same size as the data to fill it, so ' | |
| 5174 'that the\n' | |
| 5175 'alignment option has no meaning in this case.\n' | |
| 5176 '\n' | |
| 5177 'The *sign* option is only valid for number types, and can ' | |
| 5178 'be one of\n' | |
| 5179 'the following:\n' | |
| 5180 '\n' | |
| 5181 ' ' | |
| 5182 '+-----------+------------------------------------------------------------+\n' | |
| 5183 ' | Option | ' | |
| 5184 'Meaning ' | |
| 5185 '|\n' | |
| 5186 ' ' | |
| 5187 '|===========|============================================================|\n' | |
| 5188 ' | "\'+\'" | indicates that a sign should be used for ' | |
| 5189 'both positive as |\n' | |
| 5190 ' | | well as negative ' | |
| 5191 'numbers. |\n' | |
| 5192 ' ' | |
| 5193 '+-----------+------------------------------------------------------------+\n' | |
| 5194 ' | "\'-\'" | indicates that a sign should be used ' | |
| 5195 'only for negative |\n' | |
| 5196 ' | | numbers (this is the default ' | |
| 5197 'behavior). |\n' | |
| 5198 ' ' | |
| 5199 '+-----------+------------------------------------------------------------+\n' | |
| 5200 ' | space | indicates that a leading space should be ' | |
| 5201 'used on positive |\n' | |
| 5202 ' | | numbers, and a minus sign on negative ' | |
| 5203 'numbers. |\n' | |
| 5204 ' ' | |
| 5205 '+-----------+------------------------------------------------------------+\n' | |
| 5206 '\n' | |
| 5207 'The "\'#\'" option causes the “alternate form” to be used ' | |
| 5208 'for the\n' | |
| 5209 'conversion. The alternate form is defined differently for ' | |
| 5210 'different\n' | |
| 5211 'types. This option is only valid for integer, float, ' | |
| 5212 'complex and\n' | |
| 5213 'Decimal types. For integers, when binary, octal, or ' | |
| 5214 'hexadecimal output\n' | |
| 5215 'is used, this option adds the prefix respective "\'0b\'", ' | |
| 5216 '"\'0o\'", or\n' | |
| 5217 '"\'0x\'" to the output value. For floats, complex and ' | |
| 5218 'Decimal the\n' | |
| 5219 'alternate form causes the result of the conversion to ' | |
| 5220 'always contain a\n' | |
| 5221 'decimal-point character, even if no digits follow it. ' | |
| 5222 'Normally, a\n' | |
| 5223 'decimal-point character appears in the result of these ' | |
| 5224 'conversions\n' | |
| 5225 'only if a digit follows it. In addition, for "\'g\'" and ' | |
| 5226 '"\'G\'"\n' | |
| 5227 'conversions, trailing zeros are not removed from the ' | |
| 5228 'result.\n' | |
| 5229 '\n' | |
| 5230 'The "\',\'" option signals the use of a comma for a ' | |
| 5231 'thousands separator.\n' | |
| 5232 'For a locale aware separator, use the "\'n\'" integer ' | |
| 5233 'presentation type\n' | |
| 5234 'instead.\n' | |
| 5235 '\n' | |
| 5236 'Changed in version 3.1: Added the "\',\'" option (see also ' | |
| 5237 '**PEP 378**).\n' | |
| 5238 '\n' | |
| 5239 'The "\'_\'" option signals the use of an underscore for a ' | |
| 5240 'thousands\n' | |
| 5241 'separator for floating point presentation types and for ' | |
| 5242 'integer\n' | |
| 5243 'presentation type "\'d\'". For integer presentation types ' | |
| 5244 '"\'b\'", "\'o\'",\n' | |
| 5245 '"\'x\'", and "\'X\'", underscores will be inserted every 4 ' | |
| 5246 'digits. For\n' | |
| 5247 'other presentation types, specifying this option is an ' | |
| 5248 'error.\n' | |
| 5249 '\n' | |
| 5250 'Changed in version 3.6: Added the "\'_\'" option (see also ' | |
| 5251 '**PEP 515**).\n' | |
| 5252 '\n' | |
| 5253 '*width* is a decimal integer defining the minimum field ' | |
| 5254 'width. If not\n' | |
| 5255 'specified, then the field width will be determined by the ' | |
| 5256 'content.\n' | |
| 5257 '\n' | |
| 5258 'When no explicit alignment is given, preceding the *width* ' | |
| 5259 'field by a\n' | |
| 5260 'zero ("\'0\'") character enables sign-aware zero-padding ' | |
| 5261 'for numeric\n' | |
| 5262 'types. This is equivalent to a *fill* character of "\'0\'" ' | |
| 5263 'with an\n' | |
| 5264 '*alignment* type of "\'=\'".\n' | |
| 5265 '\n' | |
| 5266 'The *precision* is a decimal number indicating how many ' | |
| 5267 'digits should\n' | |
| 5268 'be displayed after the decimal point for a floating point ' | |
| 5269 'value\n' | |
| 5270 'formatted with "\'f\'" and "\'F\'", or before and after the ' | |
| 5271 'decimal point\n' | |
| 5272 'for a floating point value formatted with "\'g\'" or ' | |
| 5273 '"\'G\'". For non-\n' | |
| 5274 'number types the field indicates the maximum field size - ' | |
| 5275 'in other\n' | |
| 5276 'words, how many characters will be used from the field ' | |
| 5277 'content. The\n' | |
| 5278 '*precision* is not allowed for integer values.\n' | |
| 5279 '\n' | |
| 5280 'Finally, the *type* determines how the data should be ' | |
| 5281 'presented.\n' | |
| 5282 '\n' | |
| 5283 'The available string presentation types are:\n' | |
| 5284 '\n' | |
| 5285 ' ' | |
| 5286 '+-----------+------------------------------------------------------------+\n' | |
| 5287 ' | Type | ' | |
| 5288 'Meaning ' | |
| 5289 '|\n' | |
| 5290 ' ' | |
| 5291 '|===========|============================================================|\n' | |
| 5292 ' | "\'s\'" | String format. This is the default type ' | |
| 5293 'for strings and |\n' | |
| 5294 ' | | may be ' | |
| 5295 'omitted. |\n' | |
| 5296 ' ' | |
| 5297 '+-----------+------------------------------------------------------------+\n' | |
| 5298 ' | None | The same as ' | |
| 5299 '"\'s\'". |\n' | |
| 5300 ' ' | |
| 5301 '+-----------+------------------------------------------------------------+\n' | |
| 5302 '\n' | |
| 5303 'The available integer presentation types are:\n' | |
| 5304 '\n' | |
| 5305 ' ' | |
| 5306 '+-----------+------------------------------------------------------------+\n' | |
| 5307 ' | Type | ' | |
| 5308 'Meaning ' | |
| 5309 '|\n' | |
| 5310 ' ' | |
| 5311 '|===========|============================================================|\n' | |
| 5312 ' | "\'b\'" | Binary format. Outputs the number in ' | |
| 5313 'base 2. |\n' | |
| 5314 ' ' | |
| 5315 '+-----------+------------------------------------------------------------+\n' | |
| 5316 ' | "\'c\'" | Character. Converts the integer to the ' | |
| 5317 'corresponding |\n' | |
| 5318 ' | | unicode character before ' | |
| 5319 'printing. |\n' | |
| 5320 ' ' | |
| 5321 '+-----------+------------------------------------------------------------+\n' | |
| 5322 ' | "\'d\'" | Decimal Integer. Outputs the number in ' | |
| 5323 'base 10. |\n' | |
| 5324 ' ' | |
| 5325 '+-----------+------------------------------------------------------------+\n' | |
| 5326 ' | "\'o\'" | Octal format. Outputs the number in base ' | |
| 5327 '8. |\n' | |
| 5328 ' ' | |
| 5329 '+-----------+------------------------------------------------------------+\n' | |
| 5330 ' | "\'x\'" | Hex format. Outputs the number in base ' | |
| 5331 '16, using lower- |\n' | |
| 5332 ' | | case letters for the digits above ' | |
| 5333 '9. |\n' | |
| 5334 ' ' | |
| 5335 '+-----------+------------------------------------------------------------+\n' | |
| 5336 ' | "\'X\'" | Hex format. Outputs the number in base ' | |
| 5337 '16, using upper- |\n' | |
| 5338 ' | | case letters for the digits above ' | |
| 5339 '9. |\n' | |
| 5340 ' ' | |
| 5341 '+-----------+------------------------------------------------------------+\n' | |
| 5342 ' | "\'n\'" | Number. This is the same as "\'d\'", ' | |
| 5343 'except that it uses the |\n' | |
| 5344 ' | | current locale setting to insert the ' | |
| 5345 'appropriate number |\n' | |
| 5346 ' | | separator ' | |
| 5347 'characters. |\n' | |
| 5348 ' ' | |
| 5349 '+-----------+------------------------------------------------------------+\n' | |
| 5350 ' | None | The same as ' | |
| 5351 '"\'d\'". |\n' | |
| 5352 ' ' | |
| 5353 '+-----------+------------------------------------------------------------+\n' | |
| 5354 '\n' | |
| 5355 'In addition to the above presentation types, integers can ' | |
| 5356 'be formatted\n' | |
| 5357 'with the floating point presentation types listed below ' | |
| 5358 '(except "\'n\'"\n' | |
| 5359 'and "None"). When doing so, "float()" is used to convert ' | |
| 5360 'the integer\n' | |
| 5361 'to a floating point number before formatting.\n' | |
| 5362 '\n' | |
| 5363 'The available presentation types for floating point and ' | |
| 5364 'decimal values\n' | |
| 5365 'are:\n' | |
| 5366 '\n' | |
| 5367 ' ' | |
| 5368 '+-----------+------------------------------------------------------------+\n' | |
| 5369 ' | Type | ' | |
| 5370 'Meaning ' | |
| 5371 '|\n' | |
| 5372 ' ' | |
| 5373 '|===========|============================================================|\n' | |
| 5374 ' | "\'e\'" | Exponent notation. Prints the number in ' | |
| 5375 'scientific |\n' | |
| 5376 ' | | notation using the letter ‘e’ to indicate ' | |
| 5377 'the exponent. |\n' | |
| 5378 ' | | The default precision is ' | |
| 5379 '"6". |\n' | |
| 5380 ' ' | |
| 5381 '+-----------+------------------------------------------------------------+\n' | |
| 5382 ' | "\'E\'" | Exponent notation. Same as "\'e\'" ' | |
| 5383 'except it uses an upper |\n' | |
| 5384 ' | | case ‘E’ as the separator ' | |
| 5385 'character. |\n' | |
| 5386 ' ' | |
| 5387 '+-----------+------------------------------------------------------------+\n' | |
| 5388 ' | "\'f\'" | Fixed-point notation. Displays the ' | |
| 5389 'number as a fixed-point |\n' | |
| 5390 ' | | number. The default precision is ' | |
| 5391 '"6". |\n' | |
| 5392 ' ' | |
| 5393 '+-----------+------------------------------------------------------------+\n' | |
| 5394 ' | "\'F\'" | Fixed-point notation. Same as "\'f\'", ' | |
| 5395 'but converts "nan" to |\n' | |
| 5396 ' | | "NAN" and "inf" to ' | |
| 5397 '"INF". |\n' | |
| 5398 ' ' | |
| 5399 '+-----------+------------------------------------------------------------+\n' | |
| 5400 ' | "\'g\'" | General format. For a given precision ' | |
| 5401 '"p >= 1", this |\n' | |
| 5402 ' | | rounds the number to "p" significant ' | |
| 5403 'digits and then |\n' | |
| 5404 ' | | formats the result in either fixed-point ' | |
| 5405 'format or in |\n' | |
| 5406 ' | | scientific notation, depending on its ' | |
| 5407 'magnitude. The |\n' | |
| 5408 ' | | precise rules are as follows: suppose that ' | |
| 5409 'the result |\n' | |
| 5410 ' | | formatted with presentation type "\'e\'" ' | |
| 5411 'and precision "p-1" |\n' | |
| 5412 ' | | would have exponent "exp". Then, if "m <= ' | |
| 5413 'exp < p", where |\n' | |
| 5414 ' | | "m" is -4 for floats and -6 for ' | |
| 5415 '"Decimals", the number is |\n' | |
| 5416 ' | | formatted with presentation type "\'f\'" ' | |
| 5417 'and precision |\n' | |
| 5418 ' | | "p-1-exp". Otherwise, the number is ' | |
| 5419 'formatted with |\n' | |
| 5420 ' | | presentation type "\'e\'" and precision ' | |
| 5421 '"p-1". In both cases |\n' | |
| 5422 ' | | insignificant trailing zeros are removed ' | |
| 5423 'from the |\n' | |
| 5424 ' | | significand, and the decimal point is also ' | |
| 5425 'removed if |\n' | |
| 5426 ' | | there are no remaining digits following ' | |
| 5427 'it, unless the |\n' | |
| 5428 ' | | "\'#\'" option is used. Positive and ' | |
| 5429 'negative infinity, |\n' | |
| 5430 ' | | positive and negative zero, and nans, are ' | |
| 5431 'formatted as |\n' | |
| 5432 ' | | "inf", "-inf", "0", "-0" and "nan" ' | |
| 5433 'respectively, |\n' | |
| 5434 ' | | regardless of the precision. A precision ' | |
| 5435 'of "0" is |\n' | |
| 5436 ' | | treated as equivalent to a precision of ' | |
| 5437 '"1". The default |\n' | |
| 5438 ' | | precision is ' | |
| 5439 '"6". |\n' | |
| 5440 ' ' | |
| 5441 '+-----------+------------------------------------------------------------+\n' | |
| 5442 ' | "\'G\'" | General format. Same as "\'g\'" except ' | |
| 5443 'switches to "\'E\'" if |\n' | |
| 5444 ' | | the number gets too large. The ' | |
| 5445 'representations of infinity |\n' | |
| 5446 ' | | and NaN are uppercased, ' | |
| 5447 'too. |\n' | |
| 5448 ' ' | |
| 5449 '+-----------+------------------------------------------------------------+\n' | |
| 5450 ' | "\'n\'" | Number. This is the same as "\'g\'", ' | |
| 5451 'except that it uses the |\n' | |
| 5452 ' | | current locale setting to insert the ' | |
| 5453 'appropriate number |\n' | |
| 5454 ' | | separator ' | |
| 5455 'characters. |\n' | |
| 5456 ' ' | |
| 5457 '+-----------+------------------------------------------------------------+\n' | |
| 5458 ' | "\'%\'" | Percentage. Multiplies the number by 100 ' | |
| 5459 'and displays in |\n' | |
| 5460 ' | | fixed ("\'f\'") format, followed by a ' | |
| 5461 'percent sign. |\n' | |
| 5462 ' ' | |
| 5463 '+-----------+------------------------------------------------------------+\n' | |
| 5464 ' | None | Similar to "\'g\'", except that ' | |
| 5465 'fixed-point notation, when |\n' | |
| 5466 ' | | used, has at least one digit past the ' | |
| 5467 'decimal point. The |\n' | |
| 5468 ' | | default precision is as high as needed to ' | |
| 5469 'represent the |\n' | |
| 5470 ' | | particular value. The overall effect is to ' | |
| 5471 'match the |\n' | |
| 5472 ' | | output of "str()" as altered by the other ' | |
| 5473 'format |\n' | |
| 5474 ' | | ' | |
| 5475 'modifiers. ' | |
| 5476 '|\n' | |
| 5477 ' ' | |
| 5478 '+-----------+------------------------------------------------------------+\n' | |
| 5479 '\n' | |
| 5480 '\n' | |
| 5481 'Format examples\n' | |
| 5482 '===============\n' | |
| 5483 '\n' | |
| 5484 'This section contains examples of the "str.format()" syntax ' | |
| 5485 'and\n' | |
| 5486 'comparison with the old "%"-formatting.\n' | |
| 5487 '\n' | |
| 5488 'In most of the cases the syntax is similar to the old ' | |
| 5489 '"%"-formatting,\n' | |
| 5490 'with the addition of the "{}" and with ":" used instead of ' | |
| 5491 '"%". For\n' | |
| 5492 'example, "\'%03.2f\'" can be translated to "\'{:03.2f}\'".\n' | |
| 5493 '\n' | |
| 5494 'The new format syntax also supports new and different ' | |
| 5495 'options, shown\n' | |
| 5496 'in the following examples.\n' | |
| 5497 '\n' | |
| 5498 'Accessing arguments by position:\n' | |
| 5499 '\n' | |
| 5500 " >>> '{0}, {1}, {2}'.format('a', 'b', 'c')\n" | |
| 5501 " 'a, b, c'\n" | |
| 5502 " >>> '{}, {}, {}'.format('a', 'b', 'c') # 3.1+ only\n" | |
| 5503 " 'a, b, c'\n" | |
| 5504 " >>> '{2}, {1}, {0}'.format('a', 'b', 'c')\n" | |
| 5505 " 'c, b, a'\n" | |
| 5506 " >>> '{2}, {1}, {0}'.format(*'abc') # unpacking " | |
| 5507 'argument sequence\n' | |
| 5508 " 'c, b, a'\n" | |
| 5509 " >>> '{0}{1}{0}'.format('abra', 'cad') # arguments' " | |
| 5510 'indices can be repeated\n' | |
| 5511 " 'abracadabra'\n" | |
| 5512 '\n' | |
| 5513 'Accessing arguments by name:\n' | |
| 5514 '\n' | |
| 5515 " >>> 'Coordinates: {latitude}, " | |
| 5516 "{longitude}'.format(latitude='37.24N', " | |
| 5517 "longitude='-115.81W')\n" | |
| 5518 " 'Coordinates: 37.24N, -115.81W'\n" | |
| 5519 " >>> coord = {'latitude': '37.24N', 'longitude': " | |
| 5520 "'-115.81W'}\n" | |
| 5521 " >>> 'Coordinates: {latitude}, " | |
| 5522 "{longitude}'.format(**coord)\n" | |
| 5523 " 'Coordinates: 37.24N, -115.81W'\n" | |
| 5524 '\n' | |
| 5525 'Accessing arguments’ attributes:\n' | |
| 5526 '\n' | |
| 5527 ' >>> c = 3-5j\n' | |
| 5528 " >>> ('The complex number {0} is formed from the real " | |
| 5529 "part {0.real} '\n" | |
| 5530 " ... 'and the imaginary part {0.imag}.').format(c)\n" | |
| 5531 " 'The complex number (3-5j) is formed from the real part " | |
| 5532 "3.0 and the imaginary part -5.0.'\n" | |
| 5533 ' >>> class Point:\n' | |
| 5534 ' ... def __init__(self, x, y):\n' | |
| 5535 ' ... self.x, self.y = x, y\n' | |
| 5536 ' ... def __str__(self):\n' | |
| 5537 " ... return 'Point({self.x}, " | |
| 5538 "{self.y})'.format(self=self)\n" | |
| 5539 ' ...\n' | |
| 5540 ' >>> str(Point(4, 2))\n' | |
| 5541 " 'Point(4, 2)'\n" | |
| 5542 '\n' | |
| 5543 'Accessing arguments’ items:\n' | |
| 5544 '\n' | |
| 5545 ' >>> coord = (3, 5)\n' | |
| 5546 " >>> 'X: {0[0]}; Y: {0[1]}'.format(coord)\n" | |
| 5547 " 'X: 3; Y: 5'\n" | |
| 5548 '\n' | |
| 5549 'Replacing "%s" and "%r":\n' | |
| 5550 '\n' | |
| 5551 ' >>> "repr() shows quotes: {!r}; str() doesn\'t: ' | |
| 5552 '{!s}".format(\'test1\', \'test2\')\n' | |
| 5553 ' "repr() shows quotes: \'test1\'; str() doesn\'t: test2"\n' | |
| 5554 '\n' | |
| 5555 'Aligning the text and specifying a width:\n' | |
| 5556 '\n' | |
| 5557 " >>> '{:<30}'.format('left aligned')\n" | |
| 5558 " 'left aligned '\n" | |
| 5559 " >>> '{:>30}'.format('right aligned')\n" | |
| 5560 " ' right aligned'\n" | |
| 5561 " >>> '{:^30}'.format('centered')\n" | |
| 5562 " ' centered '\n" | |
| 5563 " >>> '{:*^30}'.format('centered') # use '*' as a fill " | |
| 5564 'char\n' | |
| 5565 " '***********centered***********'\n" | |
| 5566 '\n' | |
| 5567 'Replacing "%+f", "%-f", and "% f" and specifying a sign:\n' | |
| 5568 '\n' | |
| 5569 " >>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it " | |
| 5570 'always\n' | |
| 5571 " '+3.140000; -3.140000'\n" | |
| 5572 " >>> '{: f}; {: f}'.format(3.14, -3.14) # show a space " | |
| 5573 'for positive numbers\n' | |
| 5574 " ' 3.140000; -3.140000'\n" | |
| 5575 " >>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the " | |
| 5576 "minus -- same as '{:f}; {:f}'\n" | |
| 5577 " '3.140000; -3.140000'\n" | |
| 5578 '\n' | |
| 5579 'Replacing "%x" and "%o" and converting the value to ' | |
| 5580 'different bases:\n' | |
| 5581 '\n' | |
| 5582 ' >>> # format also supports binary numbers\n' | |
| 5583 ' >>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: ' | |
| 5584 '{0:b}".format(42)\n' | |
| 5585 " 'int: 42; hex: 2a; oct: 52; bin: 101010'\n" | |
| 5586 ' >>> # with 0x, 0o, or 0b as prefix:\n' | |
| 5587 ' >>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: ' | |
| 5588 '{0:#b}".format(42)\n' | |
| 5589 " 'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'\n" | |
| 5590 '\n' | |
| 5591 'Using the comma as a thousands separator:\n' | |
| 5592 '\n' | |
| 5593 " >>> '{:,}'.format(1234567890)\n" | |
| 5594 " '1,234,567,890'\n" | |
| 5595 '\n' | |
| 5596 'Expressing a percentage:\n' | |
| 5597 '\n' | |
| 5598 ' >>> points = 19\n' | |
| 5599 ' >>> total = 22\n' | |
| 5600 " >>> 'Correct answers: {:.2%}'.format(points/total)\n" | |
| 5601 " 'Correct answers: 86.36%'\n" | |
| 5602 '\n' | |
| 5603 'Using type-specific formatting:\n' | |
| 5604 '\n' | |
| 5605 ' >>> import datetime\n' | |
| 5606 ' >>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)\n' | |
| 5607 " >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)\n" | |
| 5608 " '2010-07-04 12:15:58'\n" | |
| 5609 '\n' | |
| 5610 'Nesting arguments and more complex examples:\n' | |
| 5611 '\n' | |
| 5612 " >>> for align, text in zip('<^>', ['left', 'center', " | |
| 5613 "'right']):\n" | |
| 5614 " ... '{0:{fill}{align}16}'.format(text, fill=align, " | |
| 5615 'align=align)\n' | |
| 5616 ' ...\n' | |
| 5617 " 'left<<<<<<<<<<<<'\n" | |
| 5618 " '^^^^^center^^^^^'\n" | |
| 5619 " '>>>>>>>>>>>right'\n" | |
| 5620 ' >>>\n' | |
| 5621 ' >>> octets = [192, 168, 0, 1]\n' | |
| 5622 " >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)\n" | |
| 5623 " 'C0A80001'\n" | |
| 5624 ' >>> int(_, 16)\n' | |
| 5625 ' 3232235521\n' | |
| 5626 ' >>>\n' | |
| 5627 ' >>> width = 5\n' | |
| 5628 ' >>> for num in range(5,12): \n' | |
| 5629 " ... for base in 'dXob':\n" | |
| 5630 " ... print('{0:{width}{base}}'.format(num, " | |
| 5631 "base=base, width=width), end=' ')\n" | |
| 5632 ' ... print()\n' | |
| 5633 ' ...\n' | |
| 5634 ' 5 5 5 101\n' | |
| 5635 ' 6 6 6 110\n' | |
| 5636 ' 7 7 7 111\n' | |
| 5637 ' 8 8 10 1000\n' | |
| 5638 ' 9 9 11 1001\n' | |
| 5639 ' 10 A 12 1010\n' | |
| 5640 ' 11 B 13 1011\n', | |
| 5641 'function': 'Function definitions\n' | |
| 5642 '********************\n' | |
| 5643 '\n' | |
| 5644 'A function definition defines a user-defined function object ' | |
| 5645 '(see\n' | |
| 5646 'section The standard type hierarchy):\n' | |
| 5647 '\n' | |
| 5648 ' funcdef ::= [decorators] "def" funcname "(" ' | |
| 5649 '[parameter_list] ")"\n' | |
| 5650 ' ["->" expression] ":" suite\n' | |
| 5651 ' decorators ::= decorator+\n' | |
| 5652 ' decorator ::= "@" dotted_name ["(" ' | |
| 5653 '[argument_list [","]] ")"] NEWLINE\n' | |
| 5654 ' dotted_name ::= identifier ("." identifier)*\n' | |
| 5655 ' parameter_list ::= defparameter ("," ' | |
| 5656 'defparameter)* "," "/" ["," [parameter_list_no_posonly]]\n' | |
| 5657 ' | parameter_list_no_posonly\n' | |
| 5658 ' parameter_list_no_posonly ::= defparameter ("," ' | |
| 5659 'defparameter)* ["," [parameter_list_starargs]]\n' | |
| 5660 ' | parameter_list_starargs\n' | |
| 5661 ' parameter_list_starargs ::= "*" [parameter] ("," ' | |
| 5662 'defparameter)* ["," ["**" parameter [","]]]\n' | |
| 5663 ' | "**" parameter [","]\n' | |
| 5664 ' parameter ::= identifier [":" expression]\n' | |
| 5665 ' defparameter ::= parameter ["=" expression]\n' | |
| 5666 ' funcname ::= identifier\n' | |
| 5667 '\n' | |
| 5668 'A function definition is an executable statement. Its execution ' | |
| 5669 'binds\n' | |
| 5670 'the function name in the current local namespace to a function ' | |
| 5671 'object\n' | |
| 5672 '(a wrapper around the executable code for the function). This\n' | |
| 5673 'function object contains a reference to the current global ' | |
| 5674 'namespace\n' | |
| 5675 'as the global namespace to be used when the function is called.\n' | |
| 5676 '\n' | |
| 5677 'The function definition does not execute the function body; this ' | |
| 5678 'gets\n' | |
| 5679 'executed only when the function is called. [2]\n' | |
| 5680 '\n' | |
| 5681 'A function definition may be wrapped by one or more *decorator*\n' | |
| 5682 'expressions. Decorator expressions are evaluated when the ' | |
| 5683 'function is\n' | |
| 5684 'defined, in the scope that contains the function definition. ' | |
| 5685 'The\n' | |
| 5686 'result must be a callable, which is invoked with the function ' | |
| 5687 'object\n' | |
| 5688 'as the only argument. The returned value is bound to the ' | |
| 5689 'function name\n' | |
| 5690 'instead of the function object. Multiple decorators are applied ' | |
| 5691 'in\n' | |
| 5692 'nested fashion. For example, the following code\n' | |
| 5693 '\n' | |
| 5694 ' @f1(arg)\n' | |
| 5695 ' @f2\n' | |
| 5696 ' def func(): pass\n' | |
| 5697 '\n' | |
| 5698 'is roughly equivalent to\n' | |
| 5699 '\n' | |
| 5700 ' def func(): pass\n' | |
| 5701 ' func = f1(arg)(f2(func))\n' | |
| 5702 '\n' | |
| 5703 'except that the original function is not temporarily bound to ' | |
| 5704 'the name\n' | |
| 5705 '"func".\n' | |
| 5706 '\n' | |
| 5707 'When one or more *parameters* have the form *parameter* "="\n' | |
| 5708 '*expression*, the function is said to have “default parameter ' | |
| 5709 'values.”\n' | |
| 5710 'For a parameter with a default value, the corresponding ' | |
| 5711 '*argument* may\n' | |
| 5712 'be omitted from a call, in which case the parameter’s default ' | |
| 5713 'value is\n' | |
| 5714 'substituted. If a parameter has a default value, all following\n' | |
| 5715 'parameters up until the “"*"” must also have a default value — ' | |
| 5716 'this is\n' | |
| 5717 'a syntactic restriction that is not expressed by the grammar.\n' | |
| 5718 '\n' | |
| 5719 '**Default parameter values are evaluated from left to right when ' | |
| 5720 'the\n' | |
| 5721 'function definition is executed.** This means that the ' | |
| 5722 'expression is\n' | |
| 5723 'evaluated once, when the function is defined, and that the same ' | |
| 5724 '“pre-\n' | |
| 5725 'computed” value is used for each call. This is especially ' | |
| 5726 'important\n' | |
| 5727 'to understand when a default parameter is a mutable object, such ' | |
| 5728 'as a\n' | |
| 5729 'list or a dictionary: if the function modifies the object (e.g. ' | |
| 5730 'by\n' | |
| 5731 'appending an item to a list), the default value is in effect ' | |
| 5732 'modified.\n' | |
| 5733 'This is generally not what was intended. A way around this is ' | |
| 5734 'to use\n' | |
| 5735 '"None" as the default, and explicitly test for it in the body of ' | |
| 5736 'the\n' | |
| 5737 'function, e.g.:\n' | |
| 5738 '\n' | |
| 5739 ' def whats_on_the_telly(penguin=None):\n' | |
| 5740 ' if penguin is None:\n' | |
| 5741 ' penguin = []\n' | |
| 5742 ' penguin.append("property of the zoo")\n' | |
| 5743 ' return penguin\n' | |
| 5744 '\n' | |
| 5745 'Function call semantics are described in more detail in section ' | |
| 5746 'Calls.\n' | |
| 5747 'A function call always assigns values to all parameters ' | |
| 5748 'mentioned in\n' | |
| 5749 'the parameter list, either from position arguments, from ' | |
| 5750 'keyword\n' | |
| 5751 'arguments, or from default values. If the form “"*identifier"” ' | |
| 5752 'is\n' | |
| 5753 'present, it is initialized to a tuple receiving any excess ' | |
| 5754 'positional\n' | |
| 5755 'parameters, defaulting to the empty tuple. If the form\n' | |
| 5756 '“"**identifier"” is present, it is initialized to a new ordered\n' | |
| 5757 'mapping receiving any excess keyword arguments, defaulting to a ' | |
| 5758 'new\n' | |
| 5759 'empty mapping of the same type. Parameters after “"*"” or\n' | |
| 5760 '“"*identifier"” are keyword-only parameters and may only be ' | |
| 5761 'passed\n' | |
| 5762 'used keyword arguments.\n' | |
| 5763 '\n' | |
| 5764 'Parameters may have an *annotation* of the form “": ' | |
| 5765 'expression"”\n' | |
| 5766 'following the parameter name. Any parameter may have an ' | |
| 5767 'annotation,\n' | |
| 5768 'even those of the form "*identifier" or "**identifier". ' | |
| 5769 'Functions may\n' | |
| 5770 'have “return” annotation of the form “"-> expression"” after ' | |
| 5771 'the\n' | |
| 5772 'parameter list. These annotations can be any valid Python ' | |
| 5773 'expression.\n' | |
| 5774 'The presence of annotations does not change the semantics of a\n' | |
| 5775 'function. The annotation values are available as values of a\n' | |
| 5776 'dictionary keyed by the parameters’ names in the ' | |
| 5777 '"__annotations__"\n' | |
| 5778 'attribute of the function object. If the "annotations" import ' | |
| 5779 'from\n' | |
| 5780 '"__future__" is used, annotations are preserved as strings at ' | |
| 5781 'runtime\n' | |
| 5782 'which enables postponed evaluation. Otherwise, they are ' | |
| 5783 'evaluated\n' | |
| 5784 'when the function definition is executed. In this case ' | |
| 5785 'annotations\n' | |
| 5786 'may be evaluated in a different order than they appear in the ' | |
| 5787 'source\n' | |
| 5788 'code.\n' | |
| 5789 '\n' | |
| 5790 'It is also possible to create anonymous functions (functions not ' | |
| 5791 'bound\n' | |
| 5792 'to a name), for immediate use in expressions. This uses lambda\n' | |
| 5793 'expressions, described in section Lambdas. Note that the ' | |
| 5794 'lambda\n' | |
| 5795 'expression is merely a shorthand for a simplified function ' | |
| 5796 'definition;\n' | |
| 5797 'a function defined in a “"def"” statement can be passed around ' | |
| 5798 'or\n' | |
| 5799 'assigned to another name just like a function defined by a ' | |
| 5800 'lambda\n' | |
| 5801 'expression. The “"def"” form is actually more powerful since ' | |
| 5802 'it\n' | |
| 5803 'allows the execution of multiple statements and annotations.\n' | |
| 5804 '\n' | |
| 5805 '**Programmer’s note:** Functions are first-class objects. A ' | |
| 5806 '“"def"”\n' | |
| 5807 'statement executed inside a function definition defines a local\n' | |
| 5808 'function that can be returned or passed around. Free variables ' | |
| 5809 'used\n' | |
| 5810 'in the nested function can access the local variables of the ' | |
| 5811 'function\n' | |
| 5812 'containing the def. See section Naming and binding for ' | |
| 5813 'details.\n' | |
| 5814 '\n' | |
| 5815 'See also:\n' | |
| 5816 '\n' | |
| 5817 ' **PEP 3107** - Function Annotations\n' | |
| 5818 ' The original specification for function annotations.\n' | |
| 5819 '\n' | |
| 5820 ' **PEP 484** - Type Hints\n' | |
| 5821 ' Definition of a standard meaning for annotations: type ' | |
| 5822 'hints.\n' | |
| 5823 '\n' | |
| 5824 ' **PEP 526** - Syntax for Variable Annotations\n' | |
| 5825 ' Ability to type hint variable declarations, including ' | |
| 5826 'class\n' | |
| 5827 ' variables and instance variables\n' | |
| 5828 '\n' | |
| 5829 ' **PEP 563** - Postponed Evaluation of Annotations\n' | |
| 5830 ' Support for forward references within annotations by ' | |
| 5831 'preserving\n' | |
| 5832 ' annotations in a string form at runtime instead of eager\n' | |
| 5833 ' evaluation.\n', | |
| 5834 'global': 'The "global" statement\n' | |
| 5835 '**********************\n' | |
| 5836 '\n' | |
| 5837 ' global_stmt ::= "global" identifier ("," identifier)*\n' | |
| 5838 '\n' | |
| 5839 'The "global" statement is a declaration which holds for the ' | |
| 5840 'entire\n' | |
| 5841 'current code block. It means that the listed identifiers are to ' | |
| 5842 'be\n' | |
| 5843 'interpreted as globals. It would be impossible to assign to a ' | |
| 5844 'global\n' | |
| 5845 'variable without "global", although free variables may refer to\n' | |
| 5846 'globals without being declared global.\n' | |
| 5847 '\n' | |
| 5848 'Names listed in a "global" statement must not be used in the same ' | |
| 5849 'code\n' | |
| 5850 'block textually preceding that "global" statement.\n' | |
| 5851 '\n' | |
| 5852 'Names listed in a "global" statement must not be defined as ' | |
| 5853 'formal\n' | |
| 5854 'parameters or in a "for" loop control target, "class" definition,\n' | |
| 5855 'function definition, "import" statement, or variable annotation.\n' | |
| 5856 '\n' | |
| 5857 '**CPython implementation detail:** The current implementation does ' | |
| 5858 'not\n' | |
| 5859 'enforce some of these restrictions, but programs should not abuse ' | |
| 5860 'this\n' | |
| 5861 'freedom, as future implementations may enforce them or silently ' | |
| 5862 'change\n' | |
| 5863 'the meaning of the program.\n' | |
| 5864 '\n' | |
| 5865 '**Programmer’s note:** "global" is a directive to the parser. It\n' | |
| 5866 'applies only to code parsed at the same time as the "global"\n' | |
| 5867 'statement. In particular, a "global" statement contained in a ' | |
| 5868 'string\n' | |
| 5869 'or code object supplied to the built-in "exec()" function does ' | |
| 5870 'not\n' | |
| 5871 'affect the code block *containing* the function call, and code\n' | |
| 5872 'contained in such a string is unaffected by "global" statements in ' | |
| 5873 'the\n' | |
| 5874 'code containing the function call. The same applies to the ' | |
| 5875 '"eval()"\n' | |
| 5876 'and "compile()" functions.\n', | |
| 5877 'id-classes': 'Reserved classes of identifiers\n' | |
| 5878 '*******************************\n' | |
| 5879 '\n' | |
| 5880 'Certain classes of identifiers (besides keywords) have ' | |
| 5881 'special\n' | |
| 5882 'meanings. These classes are identified by the patterns of ' | |
| 5883 'leading and\n' | |
| 5884 'trailing underscore characters:\n' | |
| 5885 '\n' | |
| 5886 '"_*"\n' | |
| 5887 ' Not imported by "from module import *". The special ' | |
| 5888 'identifier "_"\n' | |
| 5889 ' is used in the interactive interpreter to store the result ' | |
| 5890 'of the\n' | |
| 5891 ' last evaluation; it is stored in the "builtins" module. ' | |
| 5892 'When not\n' | |
| 5893 ' in interactive mode, "_" has no special meaning and is not ' | |
| 5894 'defined.\n' | |
| 5895 ' See section The import statement.\n' | |
| 5896 '\n' | |
| 5897 ' Note: The name "_" is often used in conjunction with\n' | |
| 5898 ' internationalization; refer to the documentation for the\n' | |
| 5899 ' "gettext" module for more information on this ' | |
| 5900 'convention.\n' | |
| 5901 '\n' | |
| 5902 '"__*__"\n' | |
| 5903 ' System-defined names. These names are defined by the ' | |
| 5904 'interpreter\n' | |
| 5905 ' and its implementation (including the standard library). ' | |
| 5906 'Current\n' | |
| 5907 ' system names are discussed in the Special method names ' | |
| 5908 'section and\n' | |
| 5909 ' elsewhere. More will likely be defined in future versions ' | |
| 5910 'of\n' | |
| 5911 ' Python. *Any* use of "__*__" names, in any context, that ' | |
| 5912 'does not\n' | |
| 5913 ' follow explicitly documented use, is subject to breakage ' | |
| 5914 'without\n' | |
| 5915 ' warning.\n' | |
| 5916 '\n' | |
| 5917 '"__*"\n' | |
| 5918 ' Class-private names. Names in this category, when used ' | |
| 5919 'within the\n' | |
| 5920 ' context of a class definition, are re-written to use a ' | |
| 5921 'mangled form\n' | |
| 5922 ' to help avoid name clashes between “private” attributes of ' | |
| 5923 'base and\n' | |
| 5924 ' derived classes. See section Identifiers (Names).\n', | |
| 5925 'identifiers': 'Identifiers and keywords\n' | |
| 5926 '************************\n' | |
| 5927 '\n' | |
| 5928 'Identifiers (also referred to as *names*) are described by ' | |
| 5929 'the\n' | |
| 5930 'following lexical definitions.\n' | |
| 5931 '\n' | |
| 5932 'The syntax of identifiers in Python is based on the Unicode ' | |
| 5933 'standard\n' | |
| 5934 'annex UAX-31, with elaboration and changes as defined below; ' | |
| 5935 'see also\n' | |
| 5936 '**PEP 3131** for further details.\n' | |
| 5937 '\n' | |
| 5938 'Within the ASCII range (U+0001..U+007F), the valid characters ' | |
| 5939 'for\n' | |
| 5940 'identifiers are the same as in Python 2.x: the uppercase and ' | |
| 5941 'lowercase\n' | |
| 5942 'letters "A" through "Z", the underscore "_" and, except for ' | |
| 5943 'the first\n' | |
| 5944 'character, the digits "0" through "9".\n' | |
| 5945 '\n' | |
| 5946 'Python 3.0 introduces additional characters from outside the ' | |
| 5947 'ASCII\n' | |
| 5948 'range (see **PEP 3131**). For these characters, the ' | |
| 5949 'classification\n' | |
| 5950 'uses the version of the Unicode Character Database as ' | |
| 5951 'included in the\n' | |
| 5952 '"unicodedata" module.\n' | |
| 5953 '\n' | |
| 5954 'Identifiers are unlimited in length. Case is significant.\n' | |
| 5955 '\n' | |
| 5956 ' identifier ::= xid_start xid_continue*\n' | |
| 5957 ' id_start ::= <all characters in general categories Lu, ' | |
| 5958 'Ll, Lt, Lm, Lo, Nl, the underscore, and characters with the ' | |
| 5959 'Other_ID_Start property>\n' | |
| 5960 ' id_continue ::= <all characters in id_start, plus ' | |
| 5961 'characters in the categories Mn, Mc, Nd, Pc and others with ' | |
| 5962 'the Other_ID_Continue property>\n' | |
| 5963 ' xid_start ::= <all characters in id_start whose NFKC ' | |
| 5964 'normalization is in "id_start xid_continue*">\n' | |
| 5965 ' xid_continue ::= <all characters in id_continue whose NFKC ' | |
| 5966 'normalization is in "id_continue*">\n' | |
| 5967 '\n' | |
| 5968 'The Unicode category codes mentioned above stand for:\n' | |
| 5969 '\n' | |
| 5970 '* *Lu* - uppercase letters\n' | |
| 5971 '\n' | |
| 5972 '* *Ll* - lowercase letters\n' | |
| 5973 '\n' | |
| 5974 '* *Lt* - titlecase letters\n' | |
| 5975 '\n' | |
| 5976 '* *Lm* - modifier letters\n' | |
| 5977 '\n' | |
| 5978 '* *Lo* - other letters\n' | |
| 5979 '\n' | |
| 5980 '* *Nl* - letter numbers\n' | |
| 5981 '\n' | |
| 5982 '* *Mn* - nonspacing marks\n' | |
| 5983 '\n' | |
| 5984 '* *Mc* - spacing combining marks\n' | |
| 5985 '\n' | |
| 5986 '* *Nd* - decimal numbers\n' | |
| 5987 '\n' | |
| 5988 '* *Pc* - connector punctuations\n' | |
| 5989 '\n' | |
| 5990 '* *Other_ID_Start* - explicit list of characters in ' | |
| 5991 'PropList.txt to\n' | |
| 5992 ' support backwards compatibility\n' | |
| 5993 '\n' | |
| 5994 '* *Other_ID_Continue* - likewise\n' | |
| 5995 '\n' | |
| 5996 'All identifiers are converted into the normal form NFKC while ' | |
| 5997 'parsing;\n' | |
| 5998 'comparison of identifiers is based on NFKC.\n' | |
| 5999 '\n' | |
| 6000 'A non-normative HTML file listing all valid identifier ' | |
| 6001 'characters for\n' | |
| 6002 'Unicode 4.1 can be found at https://www.dcl.hpi.uni-\n' | |
| 6003 'potsdam.de/home/loewis/table-3131.html.\n' | |
| 6004 '\n' | |
| 6005 '\n' | |
| 6006 'Keywords\n' | |
| 6007 '========\n' | |
| 6008 '\n' | |
| 6009 'The following identifiers are used as reserved words, or ' | |
| 6010 '*keywords* of\n' | |
| 6011 'the language, and cannot be used as ordinary identifiers. ' | |
| 6012 'They must\n' | |
| 6013 'be spelled exactly as written here:\n' | |
| 6014 '\n' | |
| 6015 ' False await else import pass\n' | |
| 6016 ' None break except in raise\n' | |
| 6017 ' True class finally is return\n' | |
| 6018 ' and continue for lambda try\n' | |
| 6019 ' as def from nonlocal while\n' | |
| 6020 ' assert del global not with\n' | |
| 6021 ' async elif if or yield\n' | |
| 6022 '\n' | |
| 6023 '\n' | |
| 6024 'Reserved classes of identifiers\n' | |
| 6025 '===============================\n' | |
| 6026 '\n' | |
| 6027 'Certain classes of identifiers (besides keywords) have ' | |
| 6028 'special\n' | |
| 6029 'meanings. These classes are identified by the patterns of ' | |
| 6030 'leading and\n' | |
| 6031 'trailing underscore characters:\n' | |
| 6032 '\n' | |
| 6033 '"_*"\n' | |
| 6034 ' Not imported by "from module import *". The special ' | |
| 6035 'identifier "_"\n' | |
| 6036 ' is used in the interactive interpreter to store the result ' | |
| 6037 'of the\n' | |
| 6038 ' last evaluation; it is stored in the "builtins" module. ' | |
| 6039 'When not\n' | |
| 6040 ' in interactive mode, "_" has no special meaning and is not ' | |
| 6041 'defined.\n' | |
| 6042 ' See section The import statement.\n' | |
| 6043 '\n' | |
| 6044 ' Note: The name "_" is often used in conjunction with\n' | |
| 6045 ' internationalization; refer to the documentation for ' | |
| 6046 'the\n' | |
| 6047 ' "gettext" module for more information on this ' | |
| 6048 'convention.\n' | |
| 6049 '\n' | |
| 6050 '"__*__"\n' | |
| 6051 ' System-defined names. These names are defined by the ' | |
| 6052 'interpreter\n' | |
| 6053 ' and its implementation (including the standard library). ' | |
| 6054 'Current\n' | |
| 6055 ' system names are discussed in the Special method names ' | |
| 6056 'section and\n' | |
| 6057 ' elsewhere. More will likely be defined in future versions ' | |
| 6058 'of\n' | |
| 6059 ' Python. *Any* use of "__*__" names, in any context, that ' | |
| 6060 'does not\n' | |
| 6061 ' follow explicitly documented use, is subject to breakage ' | |
| 6062 'without\n' | |
| 6063 ' warning.\n' | |
| 6064 '\n' | |
| 6065 '"__*"\n' | |
| 6066 ' Class-private names. Names in this category, when used ' | |
| 6067 'within the\n' | |
| 6068 ' context of a class definition, are re-written to use a ' | |
| 6069 'mangled form\n' | |
| 6070 ' to help avoid name clashes between “private” attributes of ' | |
| 6071 'base and\n' | |
| 6072 ' derived classes. See section Identifiers (Names).\n', | |
| 6073 'if': 'The "if" statement\n' | |
| 6074 '******************\n' | |
| 6075 '\n' | |
| 6076 'The "if" statement is used for conditional execution:\n' | |
| 6077 '\n' | |
| 6078 ' if_stmt ::= "if" expression ":" suite\n' | |
| 6079 ' ("elif" expression ":" suite)*\n' | |
| 6080 ' ["else" ":" suite]\n' | |
| 6081 '\n' | |
| 6082 'It selects exactly one of the suites by evaluating the expressions ' | |
| 6083 'one\n' | |
| 6084 'by one until one is found to be true (see section Boolean operations\n' | |
| 6085 'for the definition of true and false); then that suite is executed\n' | |
| 6086 '(and no other part of the "if" statement is executed or evaluated).\n' | |
| 6087 'If all expressions are false, the suite of the "else" clause, if\n' | |
| 6088 'present, is executed.\n', | |
| 6089 'imaginary': 'Imaginary literals\n' | |
| 6090 '******************\n' | |
| 6091 '\n' | |
| 6092 'Imaginary literals are described by the following lexical ' | |
| 6093 'definitions:\n' | |
| 6094 '\n' | |
| 6095 ' imagnumber ::= (floatnumber | digitpart) ("j" | "J")\n' | |
| 6096 '\n' | |
| 6097 'An imaginary literal yields a complex number with a real part ' | |
| 6098 'of 0.0.\n' | |
| 6099 'Complex numbers are represented as a pair of floating point ' | |
| 6100 'numbers\n' | |
| 6101 'and have the same restrictions on their range. To create a ' | |
| 6102 'complex\n' | |
| 6103 'number with a nonzero real part, add a floating point number to ' | |
| 6104 'it,\n' | |
| 6105 'e.g., "(3+4j)". Some examples of imaginary literals:\n' | |
| 6106 '\n' | |
| 6107 ' 3.14j 10.j 10j .001j 1e100j 3.14e-10j ' | |
| 6108 '3.14_15_93j\n', | |
| 6109 'import': 'The "import" statement\n' | |
| 6110 '**********************\n' | |
| 6111 '\n' | |
| 6112 ' import_stmt ::= "import" module ["as" identifier] ("," ' | |
| 6113 'module ["as" identifier])*\n' | |
| 6114 ' | "from" relative_module "import" identifier ' | |
| 6115 '["as" identifier]\n' | |
| 6116 ' ("," identifier ["as" identifier])*\n' | |
| 6117 ' | "from" relative_module "import" "(" ' | |
| 6118 'identifier ["as" identifier]\n' | |
| 6119 ' ("," identifier ["as" identifier])* [","] ")"\n' | |
| 6120 ' | "from" module "import" "*"\n' | |
| 6121 ' module ::= (identifier ".")* identifier\n' | |
| 6122 ' relative_module ::= "."* module | "."+\n' | |
| 6123 '\n' | |
| 6124 'The basic import statement (no "from" clause) is executed in two\n' | |
| 6125 'steps:\n' | |
| 6126 '\n' | |
| 6127 '1. find a module, loading and initializing it if necessary\n' | |
| 6128 '\n' | |
| 6129 '2. define a name or names in the local namespace for the scope\n' | |
| 6130 ' where the "import" statement occurs.\n' | |
| 6131 '\n' | |
| 6132 'When the statement contains multiple clauses (separated by commas) ' | |
| 6133 'the\n' | |
| 6134 'two steps are carried out separately for each clause, just as ' | |
| 6135 'though\n' | |
| 6136 'the clauses had been separated out into individual import ' | |
| 6137 'statements.\n' | |
| 6138 '\n' | |
| 6139 'The details of the first step, finding and loading modules are\n' | |
| 6140 'described in greater detail in the section on the import system, ' | |
| 6141 'which\n' | |
| 6142 'also describes the various types of packages and modules that can ' | |
| 6143 'be\n' | |
| 6144 'imported, as well as all the hooks that can be used to customize ' | |
| 6145 'the\n' | |
| 6146 'import system. Note that failures in this step may indicate ' | |
| 6147 'either\n' | |
| 6148 'that the module could not be located, *or* that an error occurred\n' | |
| 6149 'while initializing the module, which includes execution of the\n' | |
| 6150 'module’s code.\n' | |
| 6151 '\n' | |
| 6152 'If the requested module is retrieved successfully, it will be ' | |
| 6153 'made\n' | |
| 6154 'available in the local namespace in one of three ways:\n' | |
| 6155 '\n' | |
| 6156 '* If the module name is followed by "as", then the name following\n' | |
| 6157 ' "as" is bound directly to the imported module.\n' | |
| 6158 '\n' | |
| 6159 '* If no other name is specified, and the module being imported is ' | |
| 6160 'a\n' | |
| 6161 ' top level module, the module’s name is bound in the local ' | |
| 6162 'namespace\n' | |
| 6163 ' as a reference to the imported module\n' | |
| 6164 '\n' | |
| 6165 '* If the module being imported is *not* a top level module, then ' | |
| 6166 'the\n' | |
| 6167 ' name of the top level package that contains the module is bound ' | |
| 6168 'in\n' | |
| 6169 ' the local namespace as a reference to the top level package. ' | |
| 6170 'The\n' | |
| 6171 ' imported module must be accessed using its full qualified name\n' | |
| 6172 ' rather than directly\n' | |
| 6173 '\n' | |
| 6174 'The "from" form uses a slightly more complex process:\n' | |
| 6175 '\n' | |
| 6176 '1. find the module specified in the "from" clause, loading and\n' | |
| 6177 ' initializing it if necessary;\n' | |
| 6178 '\n' | |
| 6179 '2. for each of the identifiers specified in the "import" clauses:\n' | |
| 6180 '\n' | |
| 6181 ' 1. check if the imported module has an attribute by that name\n' | |
| 6182 '\n' | |
| 6183 ' 2. if not, attempt to import a submodule with that name and ' | |
| 6184 'then\n' | |
| 6185 ' check the imported module again for that attribute\n' | |
| 6186 '\n' | |
| 6187 ' 3. if the attribute is not found, "ImportError" is raised.\n' | |
| 6188 '\n' | |
| 6189 ' 4. otherwise, a reference to that value is stored in the local\n' | |
| 6190 ' namespace, using the name in the "as" clause if it is ' | |
| 6191 'present,\n' | |
| 6192 ' otherwise using the attribute name\n' | |
| 6193 '\n' | |
| 6194 'Examples:\n' | |
| 6195 '\n' | |
| 6196 ' import foo # foo imported and bound locally\n' | |
| 6197 ' import foo.bar.baz # foo.bar.baz imported, foo bound ' | |
| 6198 'locally\n' | |
| 6199 ' import foo.bar.baz as fbb # foo.bar.baz imported and bound as ' | |
| 6200 'fbb\n' | |
| 6201 ' from foo.bar import baz # foo.bar.baz imported and bound as ' | |
| 6202 'baz\n' | |
| 6203 ' from foo import attr # foo imported and foo.attr bound as ' | |
| 6204 'attr\n' | |
| 6205 '\n' | |
| 6206 'If the list of identifiers is replaced by a star ("\'*\'"), all ' | |
| 6207 'public\n' | |
| 6208 'names defined in the module are bound in the local namespace for ' | |
| 6209 'the\n' | |
| 6210 'scope where the "import" statement occurs.\n' | |
| 6211 '\n' | |
| 6212 'The *public names* defined by a module are determined by checking ' | |
| 6213 'the\n' | |
| 6214 'module’s namespace for a variable named "__all__"; if defined, it ' | |
| 6215 'must\n' | |
| 6216 'be a sequence of strings which are names defined or imported by ' | |
| 6217 'that\n' | |
| 6218 'module. The names given in "__all__" are all considered public ' | |
| 6219 'and\n' | |
| 6220 'are required to exist. If "__all__" is not defined, the set of ' | |
| 6221 'public\n' | |
| 6222 'names includes all names found in the module’s namespace which do ' | |
| 6223 'not\n' | |
| 6224 'begin with an underscore character ("\'_\'"). "__all__" should ' | |
| 6225 'contain\n' | |
| 6226 'the entire public API. It is intended to avoid accidentally ' | |
| 6227 'exporting\n' | |
| 6228 'items that are not part of the API (such as library modules which ' | |
| 6229 'were\n' | |
| 6230 'imported and used within the module).\n' | |
| 6231 '\n' | |
| 6232 'The wild card form of import — "from module import *" — is only\n' | |
| 6233 'allowed at the module level. Attempting to use it in class or\n' | |
| 6234 'function definitions will raise a "SyntaxError".\n' | |
| 6235 '\n' | |
| 6236 'When specifying what module to import you do not have to specify ' | |
| 6237 'the\n' | |
| 6238 'absolute name of the module. When a module or package is ' | |
| 6239 'contained\n' | |
| 6240 'within another package it is possible to make a relative import ' | |
| 6241 'within\n' | |
| 6242 'the same top package without having to mention the package name. ' | |
| 6243 'By\n' | |
| 6244 'using leading dots in the specified module or package after "from" ' | |
| 6245 'you\n' | |
| 6246 'can specify how high to traverse up the current package hierarchy\n' | |
| 6247 'without specifying exact names. One leading dot means the current\n' | |
| 6248 'package where the module making the import exists. Two dots means ' | |
| 6249 'up\n' | |
| 6250 'one package level. Three dots is up two levels, etc. So if you ' | |
| 6251 'execute\n' | |
| 6252 '"from . import mod" from a module in the "pkg" package then you ' | |
| 6253 'will\n' | |
| 6254 'end up importing "pkg.mod". If you execute "from ..subpkg2 import ' | |
| 6255 'mod"\n' | |
| 6256 'from within "pkg.subpkg1" you will import "pkg.subpkg2.mod". The\n' | |
| 6257 'specification for relative imports is contained in the Package\n' | |
| 6258 'Relative Imports section.\n' | |
| 6259 '\n' | |
| 6260 '"importlib.import_module()" is provided to support applications ' | |
| 6261 'that\n' | |
| 6262 'determine dynamically the modules to be loaded.\n' | |
| 6263 '\n' | |
| 6264 'Raises an auditing event "import" with arguments "module", ' | |
| 6265 '"filename",\n' | |
| 6266 '"sys.path", "sys.meta_path", "sys.path_hooks".\n' | |
| 6267 '\n' | |
| 6268 '\n' | |
| 6269 'Future statements\n' | |
| 6270 '=================\n' | |
| 6271 '\n' | |
| 6272 'A *future statement* is a directive to the compiler that a ' | |
| 6273 'particular\n' | |
| 6274 'module should be compiled using syntax or semantics that will be\n' | |
| 6275 'available in a specified future release of Python where the ' | |
| 6276 'feature\n' | |
| 6277 'becomes standard.\n' | |
| 6278 '\n' | |
| 6279 'The future statement is intended to ease migration to future ' | |
| 6280 'versions\n' | |
| 6281 'of Python that introduce incompatible changes to the language. ' | |
| 6282 'It\n' | |
| 6283 'allows use of the new features on a per-module basis before the\n' | |
| 6284 'release in which the feature becomes standard.\n' | |
| 6285 '\n' | |
| 6286 ' future_stmt ::= "from" "__future__" "import" feature ["as" ' | |
| 6287 'identifier]\n' | |
| 6288 ' ("," feature ["as" identifier])*\n' | |
| 6289 ' | "from" "__future__" "import" "(" feature ' | |
| 6290 '["as" identifier]\n' | |
| 6291 ' ("," feature ["as" identifier])* [","] ")"\n' | |
| 6292 ' feature ::= identifier\n' | |
| 6293 '\n' | |
| 6294 'A future statement must appear near the top of the module. The ' | |
| 6295 'only\n' | |
| 6296 'lines that can appear before a future statement are:\n' | |
| 6297 '\n' | |
| 6298 '* the module docstring (if any),\n' | |
| 6299 '\n' | |
| 6300 '* comments,\n' | |
| 6301 '\n' | |
| 6302 '* blank lines, and\n' | |
| 6303 '\n' | |
| 6304 '* other future statements.\n' | |
| 6305 '\n' | |
| 6306 'The only feature in Python 3.7 that requires using the future\n' | |
| 6307 'statement is "annotations".\n' | |
| 6308 '\n' | |
| 6309 'All historical features enabled by the future statement are still\n' | |
| 6310 'recognized by Python 3. The list includes "absolute_import",\n' | |
| 6311 '"division", "generators", "generator_stop", "unicode_literals",\n' | |
| 6312 '"print_function", "nested_scopes" and "with_statement". They are ' | |
| 6313 'all\n' | |
| 6314 'redundant because they are always enabled, and only kept for ' | |
| 6315 'backwards\n' | |
| 6316 'compatibility.\n' | |
| 6317 '\n' | |
| 6318 'A future statement is recognized and treated specially at compile\n' | |
| 6319 'time: Changes to the semantics of core constructs are often\n' | |
| 6320 'implemented by generating different code. It may even be the ' | |
| 6321 'case\n' | |
| 6322 'that a new feature introduces new incompatible syntax (such as a ' | |
| 6323 'new\n' | |
| 6324 'reserved word), in which case the compiler may need to parse the\n' | |
| 6325 'module differently. Such decisions cannot be pushed off until\n' | |
| 6326 'runtime.\n' | |
| 6327 '\n' | |
| 6328 'For any given release, the compiler knows which feature names ' | |
| 6329 'have\n' | |
| 6330 'been defined, and raises a compile-time error if a future ' | |
| 6331 'statement\n' | |
| 6332 'contains a feature not known to it.\n' | |
| 6333 '\n' | |
| 6334 'The direct runtime semantics are the same as for any import ' | |
| 6335 'statement:\n' | |
| 6336 'there is a standard module "__future__", described later, and it ' | |
| 6337 'will\n' | |
| 6338 'be imported in the usual way at the time the future statement is\n' | |
| 6339 'executed.\n' | |
| 6340 '\n' | |
| 6341 'The interesting runtime semantics depend on the specific feature\n' | |
| 6342 'enabled by the future statement.\n' | |
| 6343 '\n' | |
| 6344 'Note that there is nothing special about the statement:\n' | |
| 6345 '\n' | |
| 6346 ' import __future__ [as name]\n' | |
| 6347 '\n' | |
| 6348 'That is not a future statement; it’s an ordinary import statement ' | |
| 6349 'with\n' | |
| 6350 'no special semantics or syntax restrictions.\n' | |
| 6351 '\n' | |
| 6352 'Code compiled by calls to the built-in functions "exec()" and\n' | |
| 6353 '"compile()" that occur in a module "M" containing a future ' | |
| 6354 'statement\n' | |
| 6355 'will, by default, use the new syntax or semantics associated with ' | |
| 6356 'the\n' | |
| 6357 'future statement. This can be controlled by optional arguments ' | |
| 6358 'to\n' | |
| 6359 '"compile()" — see the documentation of that function for details.\n' | |
| 6360 '\n' | |
| 6361 'A future statement typed at an interactive interpreter prompt ' | |
| 6362 'will\n' | |
| 6363 'take effect for the rest of the interpreter session. If an\n' | |
| 6364 'interpreter is started with the "-i" option, is passed a script ' | |
| 6365 'name\n' | |
| 6366 'to execute, and the script includes a future statement, it will be ' | |
| 6367 'in\n' | |
| 6368 'effect in the interactive session started after the script is\n' | |
| 6369 'executed.\n' | |
| 6370 '\n' | |
| 6371 'See also:\n' | |
| 6372 '\n' | |
| 6373 ' **PEP 236** - Back to the __future__\n' | |
| 6374 ' The original proposal for the __future__ mechanism.\n', | |
| 6375 'in': 'Membership test operations\n' | |
| 6376 '**************************\n' | |
| 6377 '\n' | |
| 6378 'The operators "in" and "not in" test for membership. "x in s"\n' | |
| 6379 'evaluates to "True" if *x* is a member of *s*, and "False" otherwise.\n' | |
| 6380 '"x not in s" returns the negation of "x in s". All built-in ' | |
| 6381 'sequences\n' | |
| 6382 'and set types support this as well as dictionary, for which "in" ' | |
| 6383 'tests\n' | |
| 6384 'whether the dictionary has a given key. For container types such as\n' | |
| 6385 'list, tuple, set, frozenset, dict, or collections.deque, the\n' | |
| 6386 'expression "x in y" is equivalent to "any(x is e or x == e for e in\n' | |
| 6387 'y)".\n' | |
| 6388 '\n' | |
| 6389 'For the string and bytes types, "x in y" is "True" if and only if *x*\n' | |
| 6390 'is a substring of *y*. An equivalent test is "y.find(x) != -1".\n' | |
| 6391 'Empty strings are always considered to be a substring of any other\n' | |
| 6392 'string, so """ in "abc"" will return "True".\n' | |
| 6393 '\n' | |
| 6394 'For user-defined classes which define the "__contains__()" method, "x\n' | |
| 6395 'in y" returns "True" if "y.__contains__(x)" returns a true value, and\n' | |
| 6396 '"False" otherwise.\n' | |
| 6397 '\n' | |
| 6398 'For user-defined classes which do not define "__contains__()" but do\n' | |
| 6399 'define "__iter__()", "x in y" is "True" if some value "z", for which\n' | |
| 6400 'the expression "x is z or x == z" is true, is produced while ' | |
| 6401 'iterating\n' | |
| 6402 'over "y". If an exception is raised during the iteration, it is as if\n' | |
| 6403 '"in" raised that exception.\n' | |
| 6404 '\n' | |
| 6405 'Lastly, the old-style iteration protocol is tried: if a class defines\n' | |
| 6406 '"__getitem__()", "x in y" is "True" if and only if there is a non-\n' | |
| 6407 'negative integer index *i* such that "x is y[i] or x == y[i]", and no\n' | |
| 6408 'lower integer index raises the "IndexError" exception. (If any other\n' | |
| 6409 'exception is raised, it is as if "in" raised that exception).\n' | |
| 6410 '\n' | |
| 6411 'The operator "not in" is defined to have the inverse truth value of\n' | |
| 6412 '"in".\n', | |
| 6413 'integers': 'Integer literals\n' | |
| 6414 '****************\n' | |
| 6415 '\n' | |
| 6416 'Integer literals are described by the following lexical ' | |
| 6417 'definitions:\n' | |
| 6418 '\n' | |
| 6419 ' integer ::= decinteger | bininteger | octinteger | ' | |
| 6420 'hexinteger\n' | |
| 6421 ' decinteger ::= nonzerodigit (["_"] digit)* | "0"+ (["_"] ' | |
| 6422 '"0")*\n' | |
| 6423 ' bininteger ::= "0" ("b" | "B") (["_"] bindigit)+\n' | |
| 6424 ' octinteger ::= "0" ("o" | "O") (["_"] octdigit)+\n' | |
| 6425 ' hexinteger ::= "0" ("x" | "X") (["_"] hexdigit)+\n' | |
| 6426 ' nonzerodigit ::= "1"..."9"\n' | |
| 6427 ' digit ::= "0"..."9"\n' | |
| 6428 ' bindigit ::= "0" | "1"\n' | |
| 6429 ' octdigit ::= "0"..."7"\n' | |
| 6430 ' hexdigit ::= digit | "a"..."f" | "A"..."F"\n' | |
| 6431 '\n' | |
| 6432 'There is no limit for the length of integer literals apart from ' | |
| 6433 'what\n' | |
| 6434 'can be stored in available memory.\n' | |
| 6435 '\n' | |
| 6436 'Underscores are ignored for determining the numeric value of ' | |
| 6437 'the\n' | |
| 6438 'literal. They can be used to group digits for enhanced ' | |
| 6439 'readability.\n' | |
| 6440 'One underscore can occur between digits, and after base ' | |
| 6441 'specifiers\n' | |
| 6442 'like "0x".\n' | |
| 6443 '\n' | |
| 6444 'Note that leading zeros in a non-zero decimal number are not ' | |
| 6445 'allowed.\n' | |
| 6446 'This is for disambiguation with C-style octal literals, which ' | |
| 6447 'Python\n' | |
| 6448 'used before version 3.0.\n' | |
| 6449 '\n' | |
| 6450 'Some examples of integer literals:\n' | |
| 6451 '\n' | |
| 6452 ' 7 2147483647 0o177 0b100110111\n' | |
| 6453 ' 3 79228162514264337593543950336 0o377 0xdeadbeef\n' | |
| 6454 ' 100_000_000_000 0b_1110_0101\n' | |
| 6455 '\n' | |
| 6456 'Changed in version 3.6: Underscores are now allowed for ' | |
| 6457 'grouping\n' | |
| 6458 'purposes in literals.\n', | |
| 6459 'lambda': 'Lambdas\n' | |
| 6460 '*******\n' | |
| 6461 '\n' | |
| 6462 ' lambda_expr ::= "lambda" [parameter_list] ":" ' | |
| 6463 'expression\n' | |
| 6464 ' lambda_expr_nocond ::= "lambda" [parameter_list] ":" ' | |
| 6465 'expression_nocond\n' | |
| 6466 '\n' | |
| 6467 'Lambda expressions (sometimes called lambda forms) are used to ' | |
| 6468 'create\n' | |
| 6469 'anonymous functions. The expression "lambda parameters: ' | |
| 6470 'expression"\n' | |
| 6471 'yields a function object. The unnamed object behaves like a ' | |
| 6472 'function\n' | |
| 6473 'object defined with:\n' | |
| 6474 '\n' | |
| 6475 ' def <lambda>(parameters):\n' | |
| 6476 ' return expression\n' | |
| 6477 '\n' | |
| 6478 'See section Function definitions for the syntax of parameter ' | |
| 6479 'lists.\n' | |
| 6480 'Note that functions created with lambda expressions cannot ' | |
| 6481 'contain\n' | |
| 6482 'statements or annotations.\n', | |
| 6483 'lists': 'List displays\n' | |
| 6484 '*************\n' | |
| 6485 '\n' | |
| 6486 'A list display is a possibly empty series of expressions enclosed ' | |
| 6487 'in\n' | |
| 6488 'square brackets:\n' | |
| 6489 '\n' | |
| 6490 ' list_display ::= "[" [starred_list | comprehension] "]"\n' | |
| 6491 '\n' | |
| 6492 'A list display yields a new list object, the contents being ' | |
| 6493 'specified\n' | |
| 6494 'by either a list of expressions or a comprehension. When a comma-\n' | |
| 6495 'separated list of expressions is supplied, its elements are ' | |
| 6496 'evaluated\n' | |
| 6497 'from left to right and placed into the list object in that order.\n' | |
| 6498 'When a comprehension is supplied, the list is constructed from the\n' | |
| 6499 'elements resulting from the comprehension.\n', | |
| 6500 'naming': 'Naming and binding\n' | |
| 6501 '******************\n' | |
| 6502 '\n' | |
| 6503 '\n' | |
| 6504 'Binding of names\n' | |
| 6505 '================\n' | |
| 6506 '\n' | |
| 6507 '*Names* refer to objects. Names are introduced by name binding\n' | |
| 6508 'operations.\n' | |
| 6509 '\n' | |
| 6510 'The following constructs bind names: formal parameters to ' | |
| 6511 'functions,\n' | |
| 6512 '"import" statements, class and function definitions (these bind ' | |
| 6513 'the\n' | |
| 6514 'class or function name in the defining block), and targets that ' | |
| 6515 'are\n' | |
| 6516 'identifiers if occurring in an assignment, "for" loop header, or ' | |
| 6517 'after\n' | |
| 6518 '"as" in a "with" statement or "except" clause. The "import" ' | |
| 6519 'statement\n' | |
| 6520 'of the form "from ... import *" binds all names defined in the\n' | |
| 6521 'imported module, except those beginning with an underscore. This ' | |
| 6522 'form\n' | |
| 6523 'may only be used at the module level.\n' | |
| 6524 '\n' | |
| 6525 'A target occurring in a "del" statement is also considered bound ' | |
| 6526 'for\n' | |
| 6527 'this purpose (though the actual semantics are to unbind the ' | |
| 6528 'name).\n' | |
| 6529 '\n' | |
| 6530 'Each assignment or import statement occurs within a block defined ' | |
| 6531 'by a\n' | |
| 6532 'class or function definition or at the module level (the ' | |
| 6533 'top-level\n' | |
| 6534 'code block).\n' | |
| 6535 '\n' | |
| 6536 'If a name is bound in a block, it is a local variable of that ' | |
| 6537 'block,\n' | |
| 6538 'unless declared as "nonlocal" or "global". If a name is bound at ' | |
| 6539 'the\n' | |
| 6540 'module level, it is a global variable. (The variables of the ' | |
| 6541 'module\n' | |
| 6542 'code block are local and global.) If a variable is used in a ' | |
| 6543 'code\n' | |
| 6544 'block but not defined there, it is a *free variable*.\n' | |
| 6545 '\n' | |
| 6546 'Each occurrence of a name in the program text refers to the ' | |
| 6547 '*binding*\n' | |
| 6548 'of that name established by the following name resolution rules.\n' | |
| 6549 '\n' | |
| 6550 '\n' | |
| 6551 'Resolution of names\n' | |
| 6552 '===================\n' | |
| 6553 '\n' | |
| 6554 'A *scope* defines the visibility of a name within a block. If a ' | |
| 6555 'local\n' | |
| 6556 'variable is defined in a block, its scope includes that block. If ' | |
| 6557 'the\n' | |
| 6558 'definition occurs in a function block, the scope extends to any ' | |
| 6559 'blocks\n' | |
| 6560 'contained within the defining one, unless a contained block ' | |
| 6561 'introduces\n' | |
| 6562 'a different binding for the name.\n' | |
| 6563 '\n' | |
| 6564 'When a name is used in a code block, it is resolved using the ' | |
| 6565 'nearest\n' | |
| 6566 'enclosing scope. The set of all such scopes visible to a code ' | |
| 6567 'block\n' | |
| 6568 'is called the block’s *environment*.\n' | |
| 6569 '\n' | |
| 6570 'When a name is not found at all, a "NameError" exception is ' | |
| 6571 'raised. If\n' | |
| 6572 'the current scope is a function scope, and the name refers to a ' | |
| 6573 'local\n' | |
| 6574 'variable that has not yet been bound to a value at the point where ' | |
| 6575 'the\n' | |
| 6576 'name is used, an "UnboundLocalError" exception is raised.\n' | |
| 6577 '"UnboundLocalError" is a subclass of "NameError".\n' | |
| 6578 '\n' | |
| 6579 'If a name binding operation occurs anywhere within a code block, ' | |
| 6580 'all\n' | |
| 6581 'uses of the name within the block are treated as references to ' | |
| 6582 'the\n' | |
| 6583 'current block. This can lead to errors when a name is used within ' | |
| 6584 'a\n' | |
| 6585 'block before it is bound. This rule is subtle. Python lacks\n' | |
| 6586 'declarations and allows name binding operations to occur anywhere\n' | |
| 6587 'within a code block. The local variables of a code block can be\n' | |
| 6588 'determined by scanning the entire text of the block for name ' | |
| 6589 'binding\n' | |
| 6590 'operations.\n' | |
| 6591 '\n' | |
| 6592 'If the "global" statement occurs within a block, all uses of the ' | |
| 6593 'name\n' | |
| 6594 'specified in the statement refer to the binding of that name in ' | |
| 6595 'the\n' | |
| 6596 'top-level namespace. Names are resolved in the top-level ' | |
| 6597 'namespace by\n' | |
| 6598 'searching the global namespace, i.e. the namespace of the module\n' | |
| 6599 'containing the code block, and the builtins namespace, the ' | |
| 6600 'namespace\n' | |
| 6601 'of the module "builtins". The global namespace is searched ' | |
| 6602 'first. If\n' | |
| 6603 'the name is not found there, the builtins namespace is searched. ' | |
| 6604 'The\n' | |
| 6605 '"global" statement must precede all uses of the name.\n' | |
| 6606 '\n' | |
| 6607 'The "global" statement has the same scope as a name binding ' | |
| 6608 'operation\n' | |
| 6609 'in the same block. If the nearest enclosing scope for a free ' | |
| 6610 'variable\n' | |
| 6611 'contains a global statement, the free variable is treated as a ' | |
| 6612 'global.\n' | |
| 6613 '\n' | |
| 6614 'The "nonlocal" statement causes corresponding names to refer to\n' | |
| 6615 'previously bound variables in the nearest enclosing function ' | |
| 6616 'scope.\n' | |
| 6617 '"SyntaxError" is raised at compile time if the given name does ' | |
| 6618 'not\n' | |
| 6619 'exist in any enclosing function scope.\n' | |
| 6620 '\n' | |
| 6621 'The namespace for a module is automatically created the first time ' | |
| 6622 'a\n' | |
| 6623 'module is imported. The main module for a script is always ' | |
| 6624 'called\n' | |
| 6625 '"__main__".\n' | |
| 6626 '\n' | |
| 6627 'Class definition blocks and arguments to "exec()" and "eval()" ' | |
| 6628 'are\n' | |
| 6629 'special in the context of name resolution. A class definition is ' | |
| 6630 'an\n' | |
| 6631 'executable statement that may use and define names. These ' | |
| 6632 'references\n' | |
| 6633 'follow the normal rules for name resolution with an exception ' | |
| 6634 'that\n' | |
| 6635 'unbound local variables are looked up in the global namespace. ' | |
| 6636 'The\n' | |
| 6637 'namespace of the class definition becomes the attribute dictionary ' | |
| 6638 'of\n' | |
| 6639 'the class. The scope of names defined in a class block is limited ' | |
| 6640 'to\n' | |
| 6641 'the class block; it does not extend to the code blocks of methods ' | |
| 6642 '–\n' | |
| 6643 'this includes comprehensions and generator expressions since they ' | |
| 6644 'are\n' | |
| 6645 'implemented using a function scope. This means that the ' | |
| 6646 'following\n' | |
| 6647 'will fail:\n' | |
| 6648 '\n' | |
| 6649 ' class A:\n' | |
| 6650 ' a = 42\n' | |
| 6651 ' b = list(a + i for i in range(10))\n' | |
| 6652 '\n' | |
| 6653 '\n' | |
| 6654 'Builtins and restricted execution\n' | |
| 6655 '=================================\n' | |
| 6656 '\n' | |
| 6657 '**CPython implementation detail:** Users should not touch\n' | |
| 6658 '"__builtins__"; it is strictly an implementation detail. Users\n' | |
| 6659 'wanting to override values in the builtins namespace should ' | |
| 6660 '"import"\n' | |
| 6661 'the "builtins" module and modify its attributes appropriately.\n' | |
| 6662 '\n' | |
| 6663 'The builtins namespace associated with the execution of a code ' | |
| 6664 'block\n' | |
| 6665 'is actually found by looking up the name "__builtins__" in its ' | |
| 6666 'global\n' | |
| 6667 'namespace; this should be a dictionary or a module (in the latter ' | |
| 6668 'case\n' | |
| 6669 'the module’s dictionary is used). By default, when in the ' | |
| 6670 '"__main__"\n' | |
| 6671 'module, "__builtins__" is the built-in module "builtins"; when in ' | |
| 6672 'any\n' | |
| 6673 'other module, "__builtins__" is an alias for the dictionary of ' | |
| 6674 'the\n' | |
| 6675 '"builtins" module itself.\n' | |
| 6676 '\n' | |
| 6677 '\n' | |
| 6678 'Interaction with dynamic features\n' | |
| 6679 '=================================\n' | |
| 6680 '\n' | |
| 6681 'Name resolution of free variables occurs at runtime, not at ' | |
| 6682 'compile\n' | |
| 6683 'time. This means that the following code will print 42:\n' | |
| 6684 '\n' | |
| 6685 ' i = 10\n' | |
| 6686 ' def f():\n' | |
| 6687 ' print(i)\n' | |
| 6688 ' i = 42\n' | |
| 6689 ' f()\n' | |
| 6690 '\n' | |
| 6691 'The "eval()" and "exec()" functions do not have access to the ' | |
| 6692 'full\n' | |
| 6693 'environment for resolving names. Names may be resolved in the ' | |
| 6694 'local\n' | |
| 6695 'and global namespaces of the caller. Free variables are not ' | |
| 6696 'resolved\n' | |
| 6697 'in the nearest enclosing namespace, but in the global namespace. ' | |
| 6698 '[1]\n' | |
| 6699 'The "exec()" and "eval()" functions have optional arguments to\n' | |
| 6700 'override the global and local namespace. If only one namespace ' | |
| 6701 'is\n' | |
| 6702 'specified, it is used for both.\n', | |
| 6703 'nonlocal': 'The "nonlocal" statement\n' | |
| 6704 '************************\n' | |
| 6705 '\n' | |
| 6706 ' nonlocal_stmt ::= "nonlocal" identifier ("," identifier)*\n' | |
| 6707 '\n' | |
| 6708 'The "nonlocal" statement causes the listed identifiers to refer ' | |
| 6709 'to\n' | |
| 6710 'previously bound variables in the nearest enclosing scope ' | |
| 6711 'excluding\n' | |
| 6712 'globals. This is important because the default behavior for ' | |
| 6713 'binding is\n' | |
| 6714 'to search the local namespace first. The statement allows\n' | |
| 6715 'encapsulated code to rebind variables outside of the local ' | |
| 6716 'scope\n' | |
| 6717 'besides the global (module) scope.\n' | |
| 6718 '\n' | |
| 6719 'Names listed in a "nonlocal" statement, unlike those listed in ' | |
| 6720 'a\n' | |
| 6721 '"global" statement, must refer to pre-existing bindings in an\n' | |
| 6722 'enclosing scope (the scope in which a new binding should be ' | |
| 6723 'created\n' | |
| 6724 'cannot be determined unambiguously).\n' | |
| 6725 '\n' | |
| 6726 'Names listed in a "nonlocal" statement must not collide with ' | |
| 6727 'pre-\n' | |
| 6728 'existing bindings in the local scope.\n' | |
| 6729 '\n' | |
| 6730 'See also:\n' | |
| 6731 '\n' | |
| 6732 ' **PEP 3104** - Access to Names in Outer Scopes\n' | |
| 6733 ' The specification for the "nonlocal" statement.\n', | |
| 6734 'numbers': 'Numeric literals\n' | |
| 6735 '****************\n' | |
| 6736 '\n' | |
| 6737 'There are three types of numeric literals: integers, floating ' | |
| 6738 'point\n' | |
| 6739 'numbers, and imaginary numbers. There are no complex literals\n' | |
| 6740 '(complex numbers can be formed by adding a real number and an\n' | |
| 6741 'imaginary number).\n' | |
| 6742 '\n' | |
| 6743 'Note that numeric literals do not include a sign; a phrase like ' | |
| 6744 '"-1"\n' | |
| 6745 'is actually an expression composed of the unary operator ‘"-"‘ ' | |
| 6746 'and the\n' | |
| 6747 'literal "1".\n', | |
| 6748 'numeric-types': 'Emulating numeric types\n' | |
| 6749 '***********************\n' | |
| 6750 '\n' | |
| 6751 'The following methods can be defined to emulate numeric ' | |
| 6752 'objects.\n' | |
| 6753 'Methods corresponding to operations that are not supported ' | |
| 6754 'by the\n' | |
| 6755 'particular kind of number implemented (e.g., bitwise ' | |
| 6756 'operations for\n' | |
| 6757 'non-integral numbers) should be left undefined.\n' | |
| 6758 '\n' | |
| 6759 'object.__add__(self, other)\n' | |
| 6760 'object.__sub__(self, other)\n' | |
| 6761 'object.__mul__(self, other)\n' | |
| 6762 'object.__matmul__(self, other)\n' | |
| 6763 'object.__truediv__(self, other)\n' | |
| 6764 'object.__floordiv__(self, other)\n' | |
| 6765 'object.__mod__(self, other)\n' | |
| 6766 'object.__divmod__(self, other)\n' | |
| 6767 'object.__pow__(self, other[, modulo])\n' | |
| 6768 'object.__lshift__(self, other)\n' | |
| 6769 'object.__rshift__(self, other)\n' | |
| 6770 'object.__and__(self, other)\n' | |
| 6771 'object.__xor__(self, other)\n' | |
| 6772 'object.__or__(self, other)\n' | |
| 6773 '\n' | |
| 6774 ' These methods are called to implement the binary ' | |
| 6775 'arithmetic\n' | |
| 6776 ' operations ("+", "-", "*", "@", "/", "//", "%", ' | |
| 6777 '"divmod()",\n' | |
| 6778 ' "pow()", "**", "<<", ">>", "&", "^", "|"). For ' | |
| 6779 'instance, to\n' | |
| 6780 ' evaluate the expression "x + y", where *x* is an ' | |
| 6781 'instance of a\n' | |
| 6782 ' class that has an "__add__()" method, "x.__add__(y)" is ' | |
| 6783 'called.\n' | |
| 6784 ' The "__divmod__()" method should be the equivalent to ' | |
| 6785 'using\n' | |
| 6786 ' "__floordiv__()" and "__mod__()"; it should not be ' | |
| 6787 'related to\n' | |
| 6788 ' "__truediv__()". Note that "__pow__()" should be ' | |
| 6789 'defined to accept\n' | |
| 6790 ' an optional third argument if the ternary version of the ' | |
| 6791 'built-in\n' | |
| 6792 ' "pow()" function is to be supported.\n' | |
| 6793 '\n' | |
| 6794 ' If one of those methods does not support the operation ' | |
| 6795 'with the\n' | |
| 6796 ' supplied arguments, it should return "NotImplemented".\n' | |
| 6797 '\n' | |
| 6798 'object.__radd__(self, other)\n' | |
| 6799 'object.__rsub__(self, other)\n' | |
| 6800 'object.__rmul__(self, other)\n' | |
| 6801 'object.__rmatmul__(self, other)\n' | |
| 6802 'object.__rtruediv__(self, other)\n' | |
| 6803 'object.__rfloordiv__(self, other)\n' | |
| 6804 'object.__rmod__(self, other)\n' | |
| 6805 'object.__rdivmod__(self, other)\n' | |
| 6806 'object.__rpow__(self, other)\n' | |
| 6807 'object.__rlshift__(self, other)\n' | |
| 6808 'object.__rrshift__(self, other)\n' | |
| 6809 'object.__rand__(self, other)\n' | |
| 6810 'object.__rxor__(self, other)\n' | |
| 6811 'object.__ror__(self, other)\n' | |
| 6812 '\n' | |
| 6813 ' These methods are called to implement the binary ' | |
| 6814 'arithmetic\n' | |
| 6815 ' operations ("+", "-", "*", "@", "/", "//", "%", ' | |
| 6816 '"divmod()",\n' | |
| 6817 ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' | |
| 6818 '(swapped)\n' | |
| 6819 ' operands. These functions are only called if the left ' | |
| 6820 'operand does\n' | |
| 6821 ' not support the corresponding operation [3] and the ' | |
| 6822 'operands are of\n' | |
| 6823 ' different types. [4] For instance, to evaluate the ' | |
| 6824 'expression "x -\n' | |
| 6825 ' y", where *y* is an instance of a class that has an ' | |
| 6826 '"__rsub__()"\n' | |
| 6827 ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' | |
| 6828 'returns\n' | |
| 6829 ' *NotImplemented*.\n' | |
| 6830 '\n' | |
| 6831 ' Note that ternary "pow()" will not try calling ' | |
| 6832 '"__rpow__()" (the\n' | |
| 6833 ' coercion rules would become too complicated).\n' | |
| 6834 '\n' | |
| 6835 ' Note: If the right operand’s type is a subclass of the ' | |
| 6836 'left\n' | |
| 6837 ' operand’s type and that subclass provides the ' | |
| 6838 'reflected method\n' | |
| 6839 ' for the operation, this method will be called before ' | |
| 6840 'the left\n' | |
| 6841 ' operand’s non-reflected method. This behavior allows ' | |
| 6842 'subclasses\n' | |
| 6843 ' to override their ancestors’ operations.\n' | |
| 6844 '\n' | |
| 6845 'object.__iadd__(self, other)\n' | |
| 6846 'object.__isub__(self, other)\n' | |
| 6847 'object.__imul__(self, other)\n' | |
| 6848 'object.__imatmul__(self, other)\n' | |
| 6849 'object.__itruediv__(self, other)\n' | |
| 6850 'object.__ifloordiv__(self, other)\n' | |
| 6851 'object.__imod__(self, other)\n' | |
| 6852 'object.__ipow__(self, other[, modulo])\n' | |
| 6853 'object.__ilshift__(self, other)\n' | |
| 6854 'object.__irshift__(self, other)\n' | |
| 6855 'object.__iand__(self, other)\n' | |
| 6856 'object.__ixor__(self, other)\n' | |
| 6857 'object.__ior__(self, other)\n' | |
| 6858 '\n' | |
| 6859 ' These methods are called to implement the augmented ' | |
| 6860 'arithmetic\n' | |
| 6861 ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' | |
| 6862 '"**=",\n' | |
| 6863 ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' | |
| 6864 'attempt to\n' | |
| 6865 ' do the operation in-place (modifying *self*) and return ' | |
| 6866 'the result\n' | |
| 6867 ' (which could be, but does not have to be, *self*). If a ' | |
| 6868 'specific\n' | |
| 6869 ' method is not defined, the augmented assignment falls ' | |
| 6870 'back to the\n' | |
| 6871 ' normal methods. For instance, if *x* is an instance of ' | |
| 6872 'a class\n' | |
| 6873 ' with an "__iadd__()" method, "x += y" is equivalent to ' | |
| 6874 '"x =\n' | |
| 6875 ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' | |
| 6876 '"y.__radd__(x)" are\n' | |
| 6877 ' considered, as with the evaluation of "x + y". In ' | |
| 6878 'certain\n' | |
| 6879 ' situations, augmented assignment can result in ' | |
| 6880 'unexpected errors\n' | |
| 6881 ' (see Why does a_tuple[i] += [‘item’] raise an exception ' | |
| 6882 'when the\n' | |
| 6883 ' addition works?), but this behavior is in fact part of ' | |
| 6884 'the data\n' | |
| 6885 ' model.\n' | |
| 6886 '\n' | |
| 6887 'object.__neg__(self)\n' | |
| 6888 'object.__pos__(self)\n' | |
| 6889 'object.__abs__(self)\n' | |
| 6890 'object.__invert__(self)\n' | |
| 6891 '\n' | |
| 6892 ' Called to implement the unary arithmetic operations ' | |
| 6893 '("-", "+",\n' | |
| 6894 ' "abs()" and "~").\n' | |
| 6895 '\n' | |
| 6896 'object.__complex__(self)\n' | |
| 6897 'object.__int__(self)\n' | |
| 6898 'object.__float__(self)\n' | |
| 6899 '\n' | |
| 6900 ' Called to implement the built-in functions "complex()", ' | |
| 6901 '"int()" and\n' | |
| 6902 ' "float()". Should return a value of the appropriate ' | |
| 6903 'type.\n' | |
| 6904 '\n' | |
| 6905 'object.__index__(self)\n' | |
| 6906 '\n' | |
| 6907 ' Called to implement "operator.index()", and whenever ' | |
| 6908 'Python needs\n' | |
| 6909 ' to losslessly convert the numeric object to an integer ' | |
| 6910 'object (such\n' | |
| 6911 ' as in slicing, or in the built-in "bin()", "hex()" and ' | |
| 6912 '"oct()"\n' | |
| 6913 ' functions). Presence of this method indicates that the ' | |
| 6914 'numeric\n' | |
| 6915 ' object is an integer type. Must return an integer.\n' | |
| 6916 '\n' | |
| 6917 ' If "__int__()", "__float__()" and "__complex__()" are ' | |
| 6918 'not defined\n' | |
| 6919 ' then corresponding built-in functions "int()", "float()" ' | |
| 6920 'and\n' | |
| 6921 ' "complex()" fall back to "__index__()".\n' | |
| 6922 '\n' | |
| 6923 'object.__round__(self[, ndigits])\n' | |
| 6924 'object.__trunc__(self)\n' | |
| 6925 'object.__floor__(self)\n' | |
| 6926 'object.__ceil__(self)\n' | |
| 6927 '\n' | |
| 6928 ' Called to implement the built-in function "round()" and ' | |
| 6929 '"math"\n' | |
| 6930 ' functions "trunc()", "floor()" and "ceil()". Unless ' | |
| 6931 '*ndigits* is\n' | |
| 6932 ' passed to "__round__()" all these methods should return ' | |
| 6933 'the value\n' | |
| 6934 ' of the object truncated to an "Integral" (typically an ' | |
| 6935 '"int").\n' | |
| 6936 '\n' | |
| 6937 ' If "__int__()" is not defined then the built-in function ' | |
| 6938 '"int()"\n' | |
| 6939 ' falls back to "__trunc__()".\n', | |
| 6940 'objects': 'Objects, values and types\n' | |
| 6941 '*************************\n' | |
| 6942 '\n' | |
| 6943 '*Objects* are Python’s abstraction for data. All data in a ' | |
| 6944 'Python\n' | |
| 6945 'program is represented by objects or by relations between ' | |
| 6946 'objects. (In\n' | |
| 6947 'a sense, and in conformance to Von Neumann’s model of a “stored\n' | |
| 6948 'program computer,” code is also represented by objects.)\n' | |
| 6949 '\n' | |
| 6950 'Every object has an identity, a type and a value. An object’s\n' | |
| 6951 '*identity* never changes once it has been created; you may think ' | |
| 6952 'of it\n' | |
| 6953 'as the object’s address in memory. The ‘"is"’ operator compares ' | |
| 6954 'the\n' | |
| 6955 'identity of two objects; the "id()" function returns an integer\n' | |
| 6956 'representing its identity.\n' | |
| 6957 '\n' | |
| 6958 '**CPython implementation detail:** For CPython, "id(x)" is the ' | |
| 6959 'memory\n' | |
| 6960 'address where "x" is stored.\n' | |
| 6961 '\n' | |
| 6962 'An object’s type determines the operations that the object ' | |
| 6963 'supports\n' | |
| 6964 '(e.g., “does it have a length?”) and also defines the possible ' | |
| 6965 'values\n' | |
| 6966 'for objects of that type. The "type()" function returns an ' | |
| 6967 'object’s\n' | |
| 6968 'type (which is an object itself). Like its identity, an ' | |
| 6969 'object’s\n' | |
| 6970 '*type* is also unchangeable. [1]\n' | |
| 6971 '\n' | |
| 6972 'The *value* of some objects can change. Objects whose value can\n' | |
| 6973 'change are said to be *mutable*; objects whose value is ' | |
| 6974 'unchangeable\n' | |
| 6975 'once they are created are called *immutable*. (The value of an\n' | |
| 6976 'immutable container object that contains a reference to a ' | |
| 6977 'mutable\n' | |
| 6978 'object can change when the latter’s value is changed; however ' | |
| 6979 'the\n' | |
| 6980 'container is still considered immutable, because the collection ' | |
| 6981 'of\n' | |
| 6982 'objects it contains cannot be changed. So, immutability is not\n' | |
| 6983 'strictly the same as having an unchangeable value, it is more ' | |
| 6984 'subtle.)\n' | |
| 6985 'An object’s mutability is determined by its type; for instance,\n' | |
| 6986 'numbers, strings and tuples are immutable, while dictionaries ' | |
| 6987 'and\n' | |
| 6988 'lists are mutable.\n' | |
| 6989 '\n' | |
| 6990 'Objects are never explicitly destroyed; however, when they ' | |
| 6991 'become\n' | |
| 6992 'unreachable they may be garbage-collected. An implementation is\n' | |
| 6993 'allowed to postpone garbage collection or omit it altogether — it ' | |
| 6994 'is a\n' | |
| 6995 'matter of implementation quality how garbage collection is\n' | |
| 6996 'implemented, as long as no objects are collected that are still\n' | |
| 6997 'reachable.\n' | |
| 6998 '\n' | |
| 6999 '**CPython implementation detail:** CPython currently uses a ' | |
| 7000 'reference-\n' | |
| 7001 'counting scheme with (optional) delayed detection of cyclically ' | |
| 7002 'linked\n' | |
| 7003 'garbage, which collects most objects as soon as they become\n' | |
| 7004 'unreachable, but is not guaranteed to collect garbage containing\n' | |
| 7005 'circular references. See the documentation of the "gc" module ' | |
| 7006 'for\n' | |
| 7007 'information on controlling the collection of cyclic garbage. ' | |
| 7008 'Other\n' | |
| 7009 'implementations act differently and CPython may change. Do not ' | |
| 7010 'depend\n' | |
| 7011 'on immediate finalization of objects when they become unreachable ' | |
| 7012 '(so\n' | |
| 7013 'you should always close files explicitly).\n' | |
| 7014 '\n' | |
| 7015 'Note that the use of the implementation’s tracing or debugging\n' | |
| 7016 'facilities may keep objects alive that would normally be ' | |
| 7017 'collectable.\n' | |
| 7018 'Also note that catching an exception with a ‘"try"…"except"’ ' | |
| 7019 'statement\n' | |
| 7020 'may keep objects alive.\n' | |
| 7021 '\n' | |
| 7022 'Some objects contain references to “external” resources such as ' | |
| 7023 'open\n' | |
| 7024 'files or windows. It is understood that these resources are ' | |
| 7025 'freed\n' | |
| 7026 'when the object is garbage-collected, but since garbage ' | |
| 7027 'collection is\n' | |
| 7028 'not guaranteed to happen, such objects also provide an explicit ' | |
| 7029 'way to\n' | |
| 7030 'release the external resource, usually a "close()" method. ' | |
| 7031 'Programs\n' | |
| 7032 'are strongly recommended to explicitly close such objects. The\n' | |
| 7033 '‘"try"…"finally"’ statement and the ‘"with"’ statement provide\n' | |
| 7034 'convenient ways to do this.\n' | |
| 7035 '\n' | |
| 7036 'Some objects contain references to other objects; these are ' | |
| 7037 'called\n' | |
| 7038 '*containers*. Examples of containers are tuples, lists and\n' | |
| 7039 'dictionaries. The references are part of a container’s value. ' | |
| 7040 'In\n' | |
| 7041 'most cases, when we talk about the value of a container, we imply ' | |
| 7042 'the\n' | |
| 7043 'values, not the identities of the contained objects; however, ' | |
| 7044 'when we\n' | |
| 7045 'talk about the mutability of a container, only the identities of ' | |
| 7046 'the\n' | |
| 7047 'immediately contained objects are implied. So, if an immutable\n' | |
| 7048 'container (like a tuple) contains a reference to a mutable ' | |
| 7049 'object, its\n' | |
| 7050 'value changes if that mutable object is changed.\n' | |
| 7051 '\n' | |
| 7052 'Types affect almost all aspects of object behavior. Even the\n' | |
| 7053 'importance of object identity is affected in some sense: for ' | |
| 7054 'immutable\n' | |
| 7055 'types, operations that compute new values may actually return a\n' | |
| 7056 'reference to any existing object with the same type and value, ' | |
| 7057 'while\n' | |
| 7058 'for mutable objects this is not allowed. E.g., after "a = 1; b = ' | |
| 7059 '1",\n' | |
| 7060 '"a" and "b" may or may not refer to the same object with the ' | |
| 7061 'value\n' | |
| 7062 'one, depending on the implementation, but after "c = []; d = []", ' | |
| 7063 '"c"\n' | |
| 7064 'and "d" are guaranteed to refer to two different, unique, newly\n' | |
| 7065 'created empty lists. (Note that "c = d = []" assigns the same ' | |
| 7066 'object\n' | |
| 7067 'to both "c" and "d".)\n', | |
| 7068 'operator-summary': 'Operator precedence\n' | |
| 7069 '*******************\n' | |
| 7070 '\n' | |
| 7071 'The following table summarizes the operator precedence ' | |
| 7072 'in Python, from\n' | |
| 7073 'lowest precedence (least binding) to highest precedence ' | |
| 7074 '(most\n' | |
| 7075 'binding). Operators in the same box have the same ' | |
| 7076 'precedence. Unless\n' | |
| 7077 'the syntax is explicitly given, operators are binary. ' | |
| 7078 'Operators in\n' | |
| 7079 'the same box group left to right (except for ' | |
| 7080 'exponentiation, which\n' | |
| 7081 'groups from right to left).\n' | |
| 7082 '\n' | |
| 7083 'Note that comparisons, membership tests, and identity ' | |
| 7084 'tests, all have\n' | |
| 7085 'the same precedence and have a left-to-right chaining ' | |
| 7086 'feature as\n' | |
| 7087 'described in the Comparisons section.\n' | |
| 7088 '\n' | |
| 7089 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7090 '| Operator | ' | |
| 7091 'Description |\n' | |
| 7092 '|=================================================|=======================================|\n' | |
| 7093 '| ":=" | ' | |
| 7094 'Assignment expression |\n' | |
| 7095 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7096 '| "lambda" | ' | |
| 7097 'Lambda expression |\n' | |
| 7098 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7099 '| "if" – "else" | ' | |
| 7100 'Conditional expression |\n' | |
| 7101 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7102 '| "or" | ' | |
| 7103 'Boolean OR |\n' | |
| 7104 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7105 '| "and" | ' | |
| 7106 'Boolean AND |\n' | |
| 7107 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7108 '| "not" "x" | ' | |
| 7109 'Boolean NOT |\n' | |
| 7110 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7111 '| "in", "not in", "is", "is not", "<", "<=", ">", | ' | |
| 7112 'Comparisons, including membership |\n' | |
| 7113 '| ">=", "!=", "==" | ' | |
| 7114 'tests and identity tests |\n' | |
| 7115 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7116 '| "|" | ' | |
| 7117 'Bitwise OR |\n' | |
| 7118 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7119 '| "^" | ' | |
| 7120 'Bitwise XOR |\n' | |
| 7121 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7122 '| "&" | ' | |
| 7123 'Bitwise AND |\n' | |
| 7124 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7125 '| "<<", ">>" | ' | |
| 7126 'Shifts |\n' | |
| 7127 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7128 '| "+", "-" | ' | |
| 7129 'Addition and subtraction |\n' | |
| 7130 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7131 '| "*", "@", "/", "//", "%" | ' | |
| 7132 'Multiplication, matrix |\n' | |
| 7133 '| | ' | |
| 7134 'multiplication, division, floor |\n' | |
| 7135 '| | ' | |
| 7136 'division, remainder [5] |\n' | |
| 7137 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7138 '| "+x", "-x", "~x" | ' | |
| 7139 'Positive, negative, bitwise NOT |\n' | |
| 7140 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7141 '| "**" | ' | |
| 7142 'Exponentiation [6] |\n' | |
| 7143 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7144 '| "await" "x" | ' | |
| 7145 'Await expression |\n' | |
| 7146 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7147 '| "x[index]", "x[index:index]", | ' | |
| 7148 'Subscription, slicing, call, |\n' | |
| 7149 '| "x(arguments...)", "x.attribute" | ' | |
| 7150 'attribute reference |\n' | |
| 7151 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7152 '| "(expressions...)", "[expressions...]", "{key: | ' | |
| 7153 'Binding or parenthesized expression, |\n' | |
| 7154 '| value...}", "{expressions...}" | list ' | |
| 7155 'display, dictionary display, set |\n' | |
| 7156 '| | ' | |
| 7157 'display |\n' | |
| 7158 '+-------------------------------------------------+---------------------------------------+\n' | |
| 7159 '\n' | |
| 7160 '-[ Footnotes ]-\n' | |
| 7161 '\n' | |
| 7162 '[1] While "abs(x%y) < abs(y)" is true mathematically, ' | |
| 7163 'for floats\n' | |
| 7164 ' it may not be true numerically due to roundoff. For ' | |
| 7165 'example, and\n' | |
| 7166 ' assuming a platform on which a Python float is an ' | |
| 7167 'IEEE 754 double-\n' | |
| 7168 ' precision number, in order that "-1e-100 % 1e100" ' | |
| 7169 'have the same\n' | |
| 7170 ' sign as "1e100", the computed result is "-1e-100 + ' | |
| 7171 '1e100", which\n' | |
| 7172 ' is numerically exactly equal to "1e100". The ' | |
| 7173 'function\n' | |
| 7174 ' "math.fmod()" returns a result whose sign matches ' | |
| 7175 'the sign of the\n' | |
| 7176 ' first argument instead, and so returns "-1e-100" in ' | |
| 7177 'this case.\n' | |
| 7178 ' Which approach is more appropriate depends on the ' | |
| 7179 'application.\n' | |
| 7180 '\n' | |
| 7181 '[2] If x is very close to an exact integer multiple of ' | |
| 7182 'y, it’s\n' | |
| 7183 ' possible for "x//y" to be one larger than ' | |
| 7184 '"(x-x%y)//y" due to\n' | |
| 7185 ' rounding. In such cases, Python returns the latter ' | |
| 7186 'result, in\n' | |
| 7187 ' order to preserve that "divmod(x,y)[0] * y + x % y" ' | |
| 7188 'be very close\n' | |
| 7189 ' to "x".\n' | |
| 7190 '\n' | |
| 7191 '[3] The Unicode standard distinguishes between *code ' | |
| 7192 'points* (e.g.\n' | |
| 7193 ' U+0041) and *abstract characters* (e.g. “LATIN ' | |
| 7194 'CAPITAL LETTER A”).\n' | |
| 7195 ' While most abstract characters in Unicode are only ' | |
| 7196 'represented\n' | |
| 7197 ' using one code point, there is a number of abstract ' | |
| 7198 'characters\n' | |
| 7199 ' that can in addition be represented using a sequence ' | |
| 7200 'of more than\n' | |
| 7201 ' one code point. For example, the abstract character ' | |
| 7202 '“LATIN\n' | |
| 7203 ' CAPITAL LETTER C WITH CEDILLA” can be represented as ' | |
| 7204 'a single\n' | |
| 7205 ' *precomposed character* at code position U+00C7, or ' | |
| 7206 'as a sequence\n' | |
| 7207 ' of a *base character* at code position U+0043 (LATIN ' | |
| 7208 'CAPITAL\n' | |
| 7209 ' LETTER C), followed by a *combining character* at ' | |
| 7210 'code position\n' | |
| 7211 ' U+0327 (COMBINING CEDILLA).\n' | |
| 7212 '\n' | |
| 7213 ' The comparison operators on strings compare at the ' | |
| 7214 'level of\n' | |
| 7215 ' Unicode code points. This may be counter-intuitive ' | |
| 7216 'to humans. For\n' | |
| 7217 ' example, ""\\u00C7" == "\\u0043\\u0327"" is "False", ' | |
| 7218 'even though both\n' | |
| 7219 ' strings represent the same abstract character “LATIN ' | |
| 7220 'CAPITAL\n' | |
| 7221 ' LETTER C WITH CEDILLA”.\n' | |
| 7222 '\n' | |
| 7223 ' To compare strings at the level of abstract ' | |
| 7224 'characters (that is,\n' | |
| 7225 ' in a way intuitive to humans), use ' | |
| 7226 '"unicodedata.normalize()".\n' | |
| 7227 '\n' | |
| 7228 '[4] Due to automatic garbage-collection, free lists, and ' | |
| 7229 'the\n' | |
| 7230 ' dynamic nature of descriptors, you may notice ' | |
| 7231 'seemingly unusual\n' | |
| 7232 ' behaviour in certain uses of the "is" operator, like ' | |
| 7233 'those\n' | |
| 7234 ' involving comparisons between instance methods, or ' | |
| 7235 'constants.\n' | |
| 7236 ' Check their documentation for more info.\n' | |
| 7237 '\n' | |
| 7238 '[5] The "%" operator is also used for string formatting; ' | |
| 7239 'the same\n' | |
| 7240 ' precedence applies.\n' | |
| 7241 '\n' | |
| 7242 '[6] The power operator "**" binds less tightly than an ' | |
| 7243 'arithmetic\n' | |
| 7244 ' or bitwise unary operator on its right, that is, ' | |
| 7245 '"2**-1" is "0.5".\n', | |
| 7246 'pass': 'The "pass" statement\n' | |
| 7247 '********************\n' | |
| 7248 '\n' | |
| 7249 ' pass_stmt ::= "pass"\n' | |
| 7250 '\n' | |
| 7251 '"pass" is a null operation — when it is executed, nothing happens. ' | |
| 7252 'It\n' | |
| 7253 'is useful as a placeholder when a statement is required ' | |
| 7254 'syntactically,\n' | |
| 7255 'but no code needs to be executed, for example:\n' | |
| 7256 '\n' | |
| 7257 ' def f(arg): pass # a function that does nothing (yet)\n' | |
| 7258 '\n' | |
| 7259 ' class C: pass # a class with no methods (yet)\n', | |
| 7260 'power': 'The power operator\n' | |
| 7261 '******************\n' | |
| 7262 '\n' | |
| 7263 'The power operator binds more tightly than unary operators on its\n' | |
| 7264 'left; it binds less tightly than unary operators on its right. ' | |
| 7265 'The\n' | |
| 7266 'syntax is:\n' | |
| 7267 '\n' | |
| 7268 ' power ::= (await_expr | primary) ["**" u_expr]\n' | |
| 7269 '\n' | |
| 7270 'Thus, in an unparenthesized sequence of power and unary operators, ' | |
| 7271 'the\n' | |
| 7272 'operators are evaluated from right to left (this does not ' | |
| 7273 'constrain\n' | |
| 7274 'the evaluation order for the operands): "-1**2" results in "-1".\n' | |
| 7275 '\n' | |
| 7276 'The power operator has the same semantics as the built-in "pow()"\n' | |
| 7277 'function, when called with two arguments: it yields its left ' | |
| 7278 'argument\n' | |
| 7279 'raised to the power of its right argument. The numeric arguments ' | |
| 7280 'are\n' | |
| 7281 'first converted to a common type, and the result is of that type.\n' | |
| 7282 '\n' | |
| 7283 'For int operands, the result has the same type as the operands ' | |
| 7284 'unless\n' | |
| 7285 'the second argument is negative; in that case, all arguments are\n' | |
| 7286 'converted to float and a float result is delivered. For example,\n' | |
| 7287 '"10**2" returns "100", but "10**-2" returns "0.01".\n' | |
| 7288 '\n' | |
| 7289 'Raising "0.0" to a negative power results in a ' | |
| 7290 '"ZeroDivisionError".\n' | |
| 7291 'Raising a negative number to a fractional power results in a ' | |
| 7292 '"complex"\n' | |
| 7293 'number. (In earlier versions it raised a "ValueError".)\n', | |
| 7294 'raise': 'The "raise" statement\n' | |
| 7295 '*********************\n' | |
| 7296 '\n' | |
| 7297 ' raise_stmt ::= "raise" [expression ["from" expression]]\n' | |
| 7298 '\n' | |
| 7299 'If no expressions are present, "raise" re-raises the last ' | |
| 7300 'exception\n' | |
| 7301 'that was active in the current scope. If no exception is active ' | |
| 7302 'in\n' | |
| 7303 'the current scope, a "RuntimeError" exception is raised indicating\n' | |
| 7304 'that this is an error.\n' | |
| 7305 '\n' | |
| 7306 'Otherwise, "raise" evaluates the first expression as the exception\n' | |
| 7307 'object. It must be either a subclass or an instance of\n' | |
| 7308 '"BaseException". If it is a class, the exception instance will be\n' | |
| 7309 'obtained when needed by instantiating the class with no arguments.\n' | |
| 7310 '\n' | |
| 7311 'The *type* of the exception is the exception instance’s class, the\n' | |
| 7312 '*value* is the instance itself.\n' | |
| 7313 '\n' | |
| 7314 'A traceback object is normally created automatically when an ' | |
| 7315 'exception\n' | |
| 7316 'is raised and attached to it as the "__traceback__" attribute, ' | |
| 7317 'which\n' | |
| 7318 'is writable. You can create an exception and set your own traceback ' | |
| 7319 'in\n' | |
| 7320 'one step using the "with_traceback()" exception method (which ' | |
| 7321 'returns\n' | |
| 7322 'the same exception instance, with its traceback set to its ' | |
| 7323 'argument),\n' | |
| 7324 'like so:\n' | |
| 7325 '\n' | |
| 7326 ' raise Exception("foo occurred").with_traceback(tracebackobj)\n' | |
| 7327 '\n' | |
| 7328 'The "from" clause is used for exception chaining: if given, the ' | |
| 7329 'second\n' | |
| 7330 '*expression* must be another exception class or instance, which ' | |
| 7331 'will\n' | |
| 7332 'then be attached to the raised exception as the "__cause__" ' | |
| 7333 'attribute\n' | |
| 7334 '(which is writable). If the raised exception is not handled, both\n' | |
| 7335 'exceptions will be printed:\n' | |
| 7336 '\n' | |
| 7337 ' >>> try:\n' | |
| 7338 ' ... print(1 / 0)\n' | |
| 7339 ' ... except Exception as exc:\n' | |
| 7340 ' ... raise RuntimeError("Something bad happened") from exc\n' | |
| 7341 ' ...\n' | |
| 7342 ' Traceback (most recent call last):\n' | |
| 7343 ' File "<stdin>", line 2, in <module>\n' | |
| 7344 ' ZeroDivisionError: division by zero\n' | |
| 7345 '\n' | |
| 7346 ' The above exception was the direct cause of the following ' | |
| 7347 'exception:\n' | |
| 7348 '\n' | |
| 7349 ' Traceback (most recent call last):\n' | |
| 7350 ' File "<stdin>", line 4, in <module>\n' | |
| 7351 ' RuntimeError: Something bad happened\n' | |
| 7352 '\n' | |
| 7353 'A similar mechanism works implicitly if an exception is raised ' | |
| 7354 'inside\n' | |
| 7355 'an exception handler or a "finally" clause: the previous exception ' | |
| 7356 'is\n' | |
| 7357 'then attached as the new exception’s "__context__" attribute:\n' | |
| 7358 '\n' | |
| 7359 ' >>> try:\n' | |
| 7360 ' ... print(1 / 0)\n' | |
| 7361 ' ... except:\n' | |
| 7362 ' ... raise RuntimeError("Something bad happened")\n' | |
| 7363 ' ...\n' | |
| 7364 ' Traceback (most recent call last):\n' | |
| 7365 ' File "<stdin>", line 2, in <module>\n' | |
| 7366 ' ZeroDivisionError: division by zero\n' | |
| 7367 '\n' | |
| 7368 ' During handling of the above exception, another exception ' | |
| 7369 'occurred:\n' | |
| 7370 '\n' | |
| 7371 ' Traceback (most recent call last):\n' | |
| 7372 ' File "<stdin>", line 4, in <module>\n' | |
| 7373 ' RuntimeError: Something bad happened\n' | |
| 7374 '\n' | |
| 7375 'Exception chaining can be explicitly suppressed by specifying ' | |
| 7376 '"None"\n' | |
| 7377 'in the "from" clause:\n' | |
| 7378 '\n' | |
| 7379 ' >>> try:\n' | |
| 7380 ' ... print(1 / 0)\n' | |
| 7381 ' ... except:\n' | |
| 7382 ' ... raise RuntimeError("Something bad happened") from None\n' | |
| 7383 ' ...\n' | |
| 7384 ' Traceback (most recent call last):\n' | |
| 7385 ' File "<stdin>", line 4, in <module>\n' | |
| 7386 ' RuntimeError: Something bad happened\n' | |
| 7387 '\n' | |
| 7388 'Additional information on exceptions can be found in section\n' | |
| 7389 'Exceptions, and information about handling exceptions is in ' | |
| 7390 'section\n' | |
| 7391 'The try statement.\n' | |
| 7392 '\n' | |
| 7393 'Changed in version 3.3: "None" is now permitted as "Y" in "raise X\n' | |
| 7394 'from Y".\n' | |
| 7395 '\n' | |
| 7396 'New in version 3.3: The "__suppress_context__" attribute to ' | |
| 7397 'suppress\n' | |
| 7398 'automatic display of the exception context.\n', | |
| 7399 'return': 'The "return" statement\n' | |
| 7400 '**********************\n' | |
| 7401 '\n' | |
| 7402 ' return_stmt ::= "return" [expression_list]\n' | |
| 7403 '\n' | |
| 7404 '"return" may only occur syntactically nested in a function ' | |
| 7405 'definition,\n' | |
| 7406 'not within a nested class definition.\n' | |
| 7407 '\n' | |
| 7408 'If an expression list is present, it is evaluated, else "None" is\n' | |
| 7409 'substituted.\n' | |
| 7410 '\n' | |
| 7411 '"return" leaves the current function call with the expression list ' | |
| 7412 '(or\n' | |
| 7413 '"None") as return value.\n' | |
| 7414 '\n' | |
| 7415 'When "return" passes control out of a "try" statement with a ' | |
| 7416 '"finally"\n' | |
| 7417 'clause, that "finally" clause is executed before really leaving ' | |
| 7418 'the\n' | |
| 7419 'function.\n' | |
| 7420 '\n' | |
| 7421 'In a generator function, the "return" statement indicates that ' | |
| 7422 'the\n' | |
| 7423 'generator is done and will cause "StopIteration" to be raised. ' | |
| 7424 'The\n' | |
| 7425 'returned value (if any) is used as an argument to construct\n' | |
| 7426 '"StopIteration" and becomes the "StopIteration.value" attribute.\n' | |
| 7427 '\n' | |
| 7428 'In an asynchronous generator function, an empty "return" ' | |
| 7429 'statement\n' | |
| 7430 'indicates that the asynchronous generator is done and will cause\n' | |
| 7431 '"StopAsyncIteration" to be raised. A non-empty "return" statement ' | |
| 7432 'is\n' | |
| 7433 'a syntax error in an asynchronous generator function.\n', | |
| 7434 'sequence-types': 'Emulating container types\n' | |
| 7435 '*************************\n' | |
| 7436 '\n' | |
| 7437 'The following methods can be defined to implement ' | |
| 7438 'container objects.\n' | |
| 7439 'Containers usually are sequences (such as lists or tuples) ' | |
| 7440 'or mappings\n' | |
| 7441 '(like dictionaries), but can represent other containers as ' | |
| 7442 'well. The\n' | |
| 7443 'first set of methods is used either to emulate a sequence ' | |
| 7444 'or to\n' | |
| 7445 'emulate a mapping; the difference is that for a sequence, ' | |
| 7446 'the\n' | |
| 7447 'allowable keys should be the integers *k* for which "0 <= ' | |
| 7448 'k < N" where\n' | |
| 7449 '*N* is the length of the sequence, or slice objects, which ' | |
| 7450 'define a\n' | |
| 7451 'range of items. It is also recommended that mappings ' | |
| 7452 'provide the\n' | |
| 7453 'methods "keys()", "values()", "items()", "get()", ' | |
| 7454 '"clear()",\n' | |
| 7455 '"setdefault()", "pop()", "popitem()", "copy()", and ' | |
| 7456 '"update()"\n' | |
| 7457 'behaving similar to those for Python’s standard dictionary ' | |
| 7458 'objects.\n' | |
| 7459 'The "collections.abc" module provides a "MutableMapping" ' | |
| 7460 'abstract base\n' | |
| 7461 'class to help create those methods from a base set of ' | |
| 7462 '"__getitem__()",\n' | |
| 7463 '"__setitem__()", "__delitem__()", and "keys()". Mutable ' | |
| 7464 'sequences\n' | |
| 7465 'should provide methods "append()", "count()", "index()", ' | |
| 7466 '"extend()",\n' | |
| 7467 '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' | |
| 7468 'like Python\n' | |
| 7469 'standard list objects. Finally, sequence types should ' | |
| 7470 'implement\n' | |
| 7471 'addition (meaning concatenation) and multiplication ' | |
| 7472 '(meaning\n' | |
| 7473 'repetition) by defining the methods "__add__()", ' | |
| 7474 '"__radd__()",\n' | |
| 7475 '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' | |
| 7476 'described\n' | |
| 7477 'below; they should not define other numerical operators. ' | |
| 7478 'It is\n' | |
| 7479 'recommended that both mappings and sequences implement ' | |
| 7480 'the\n' | |
| 7481 '"__contains__()" method to allow efficient use of the "in" ' | |
| 7482 'operator;\n' | |
| 7483 'for mappings, "in" should search the mapping’s keys; for ' | |
| 7484 'sequences, it\n' | |
| 7485 'should search through the values. It is further ' | |
| 7486 'recommended that both\n' | |
| 7487 'mappings and sequences implement the "__iter__()" method ' | |
| 7488 'to allow\n' | |
| 7489 'efficient iteration through the container; for mappings, ' | |
| 7490 '"__iter__()"\n' | |
| 7491 'should iterate through the object’s keys; for sequences, ' | |
| 7492 'it should\n' | |
| 7493 'iterate through the values.\n' | |
| 7494 '\n' | |
| 7495 'object.__len__(self)\n' | |
| 7496 '\n' | |
| 7497 ' Called to implement the built-in function "len()". ' | |
| 7498 'Should return\n' | |
| 7499 ' the length of the object, an integer ">=" 0. Also, an ' | |
| 7500 'object that\n' | |
| 7501 ' doesn’t define a "__bool__()" method and whose ' | |
| 7502 '"__len__()" method\n' | |
| 7503 ' returns zero is considered to be false in a Boolean ' | |
| 7504 'context.\n' | |
| 7505 '\n' | |
| 7506 ' **CPython implementation detail:** In CPython, the ' | |
| 7507 'length is\n' | |
| 7508 ' required to be at most "sys.maxsize". If the length is ' | |
| 7509 'larger than\n' | |
| 7510 ' "sys.maxsize" some features (such as "len()") may ' | |
| 7511 'raise\n' | |
| 7512 ' "OverflowError". To prevent raising "OverflowError" by ' | |
| 7513 'truth value\n' | |
| 7514 ' testing, an object must define a "__bool__()" method.\n' | |
| 7515 '\n' | |
| 7516 'object.__length_hint__(self)\n' | |
| 7517 '\n' | |
| 7518 ' Called to implement "operator.length_hint()". Should ' | |
| 7519 'return an\n' | |
| 7520 ' estimated length for the object (which may be greater ' | |
| 7521 'or less than\n' | |
| 7522 ' the actual length). The length must be an integer ">=" ' | |
| 7523 '0. The\n' | |
| 7524 ' return value may also be "NotImplemented", which is ' | |
| 7525 'treated the\n' | |
| 7526 ' same as if the "__length_hint__" method didn’t exist at ' | |
| 7527 'all. This\n' | |
| 7528 ' method is purely an optimization and is never required ' | |
| 7529 'for\n' | |
| 7530 ' correctness.\n' | |
| 7531 '\n' | |
| 7532 ' New in version 3.4.\n' | |
| 7533 '\n' | |
| 7534 'Note: Slicing is done exclusively with the following three ' | |
| 7535 'methods.\n' | |
| 7536 ' A call like\n' | |
| 7537 '\n' | |
| 7538 ' a[1:2] = b\n' | |
| 7539 '\n' | |
| 7540 ' is translated to\n' | |
| 7541 '\n' | |
| 7542 ' a[slice(1, 2, None)] = b\n' | |
| 7543 '\n' | |
| 7544 ' and so forth. Missing slice items are always filled in ' | |
| 7545 'with "None".\n' | |
| 7546 '\n' | |
| 7547 'object.__getitem__(self, key)\n' | |
| 7548 '\n' | |
| 7549 ' Called to implement evaluation of "self[key]". For ' | |
| 7550 'sequence types,\n' | |
| 7551 ' the accepted keys should be integers and slice ' | |
| 7552 'objects. Note that\n' | |
| 7553 ' the special interpretation of negative indexes (if the ' | |
| 7554 'class wishes\n' | |
| 7555 ' to emulate a sequence type) is up to the ' | |
| 7556 '"__getitem__()" method. If\n' | |
| 7557 ' *key* is of an inappropriate type, "TypeError" may be ' | |
| 7558 'raised; if of\n' | |
| 7559 ' a value outside the set of indexes for the sequence ' | |
| 7560 '(after any\n' | |
| 7561 ' special interpretation of negative values), ' | |
| 7562 '"IndexError" should be\n' | |
| 7563 ' raised. For mapping types, if *key* is missing (not in ' | |
| 7564 'the\n' | |
| 7565 ' container), "KeyError" should be raised.\n' | |
| 7566 '\n' | |
| 7567 ' Note: "for" loops expect that an "IndexError" will be ' | |
| 7568 'raised for\n' | |
| 7569 ' illegal indexes to allow proper detection of the end ' | |
| 7570 'of the\n' | |
| 7571 ' sequence.\n' | |
| 7572 '\n' | |
| 7573 'object.__setitem__(self, key, value)\n' | |
| 7574 '\n' | |
| 7575 ' Called to implement assignment to "self[key]". Same ' | |
| 7576 'note as for\n' | |
| 7577 ' "__getitem__()". This should only be implemented for ' | |
| 7578 'mappings if\n' | |
| 7579 ' the objects support changes to the values for keys, or ' | |
| 7580 'if new keys\n' | |
| 7581 ' can be added, or for sequences if elements can be ' | |
| 7582 'replaced. The\n' | |
| 7583 ' same exceptions should be raised for improper *key* ' | |
| 7584 'values as for\n' | |
| 7585 ' the "__getitem__()" method.\n' | |
| 7586 '\n' | |
| 7587 'object.__delitem__(self, key)\n' | |
| 7588 '\n' | |
| 7589 ' Called to implement deletion of "self[key]". Same note ' | |
| 7590 'as for\n' | |
| 7591 ' "__getitem__()". This should only be implemented for ' | |
| 7592 'mappings if\n' | |
| 7593 ' the objects support removal of keys, or for sequences ' | |
| 7594 'if elements\n' | |
| 7595 ' can be removed from the sequence. The same exceptions ' | |
| 7596 'should be\n' | |
| 7597 ' raised for improper *key* values as for the ' | |
| 7598 '"__getitem__()" method.\n' | |
| 7599 '\n' | |
| 7600 'object.__missing__(self, key)\n' | |
| 7601 '\n' | |
| 7602 ' Called by "dict"."__getitem__()" to implement ' | |
| 7603 '"self[key]" for dict\n' | |
| 7604 ' subclasses when key is not in the dictionary.\n' | |
| 7605 '\n' | |
| 7606 'object.__iter__(self)\n' | |
| 7607 '\n' | |
| 7608 ' This method is called when an iterator is required for ' | |
| 7609 'a container.\n' | |
| 7610 ' This method should return a new iterator object that ' | |
| 7611 'can iterate\n' | |
| 7612 ' over all the objects in the container. For mappings, ' | |
| 7613 'it should\n' | |
| 7614 ' iterate over the keys of the container.\n' | |
| 7615 '\n' | |
| 7616 ' Iterator objects also need to implement this method; ' | |
| 7617 'they are\n' | |
| 7618 ' required to return themselves. For more information on ' | |
| 7619 'iterator\n' | |
| 7620 ' objects, see Iterator Types.\n' | |
| 7621 '\n' | |
| 7622 'object.__reversed__(self)\n' | |
| 7623 '\n' | |
| 7624 ' Called (if present) by the "reversed()" built-in to ' | |
| 7625 'implement\n' | |
| 7626 ' reverse iteration. It should return a new iterator ' | |
| 7627 'object that\n' | |
| 7628 ' iterates over all the objects in the container in ' | |
| 7629 'reverse order.\n' | |
| 7630 '\n' | |
| 7631 ' If the "__reversed__()" method is not provided, the ' | |
| 7632 '"reversed()"\n' | |
| 7633 ' built-in will fall back to using the sequence protocol ' | |
| 7634 '("__len__()"\n' | |
| 7635 ' and "__getitem__()"). Objects that support the ' | |
| 7636 'sequence protocol\n' | |
| 7637 ' should only provide "__reversed__()" if they can ' | |
| 7638 'provide an\n' | |
| 7639 ' implementation that is more efficient than the one ' | |
| 7640 'provided by\n' | |
| 7641 ' "reversed()".\n' | |
| 7642 '\n' | |
| 7643 'The membership test operators ("in" and "not in") are ' | |
| 7644 'normally\n' | |
| 7645 'implemented as an iteration through a container. However, ' | |
| 7646 'container\n' | |
| 7647 'objects can supply the following special method with a ' | |
| 7648 'more efficient\n' | |
| 7649 'implementation, which also does not require the object be ' | |
| 7650 'iterable.\n' | |
| 7651 '\n' | |
| 7652 'object.__contains__(self, item)\n' | |
| 7653 '\n' | |
| 7654 ' Called to implement membership test operators. Should ' | |
| 7655 'return true\n' | |
| 7656 ' if *item* is in *self*, false otherwise. For mapping ' | |
| 7657 'objects, this\n' | |
| 7658 ' should consider the keys of the mapping rather than the ' | |
| 7659 'values or\n' | |
| 7660 ' the key-item pairs.\n' | |
| 7661 '\n' | |
| 7662 ' For objects that don’t define "__contains__()", the ' | |
| 7663 'membership test\n' | |
| 7664 ' first tries iteration via "__iter__()", then the old ' | |
| 7665 'sequence\n' | |
| 7666 ' iteration protocol via "__getitem__()", see this ' | |
| 7667 'section in the\n' | |
| 7668 ' language reference.\n', | |
| 7669 'shifting': 'Shifting operations\n' | |
| 7670 '*******************\n' | |
| 7671 '\n' | |
| 7672 'The shifting operations have lower priority than the arithmetic\n' | |
| 7673 'operations:\n' | |
| 7674 '\n' | |
| 7675 ' shift_expr ::= a_expr | shift_expr ("<<" | ">>") a_expr\n' | |
| 7676 '\n' | |
| 7677 'These operators accept integers as arguments. They shift the ' | |
| 7678 'first\n' | |
| 7679 'argument to the left or right by the number of bits given by ' | |
| 7680 'the\n' | |
| 7681 'second argument.\n' | |
| 7682 '\n' | |
| 7683 'A right shift by *n* bits is defined as floor division by ' | |
| 7684 '"pow(2,n)".\n' | |
| 7685 'A left shift by *n* bits is defined as multiplication with ' | |
| 7686 '"pow(2,n)".\n', | |
| 7687 'slicings': 'Slicings\n' | |
| 7688 '********\n' | |
| 7689 '\n' | |
| 7690 'A slicing selects a range of items in a sequence object (e.g., ' | |
| 7691 'a\n' | |
| 7692 'string, tuple or list). Slicings may be used as expressions or ' | |
| 7693 'as\n' | |
| 7694 'targets in assignment or "del" statements. The syntax for a ' | |
| 7695 'slicing:\n' | |
| 7696 '\n' | |
| 7697 ' slicing ::= primary "[" slice_list "]"\n' | |
| 7698 ' slice_list ::= slice_item ("," slice_item)* [","]\n' | |
| 7699 ' slice_item ::= expression | proper_slice\n' | |
| 7700 ' proper_slice ::= [lower_bound] ":" [upper_bound] [ ":" ' | |
| 7701 '[stride] ]\n' | |
| 7702 ' lower_bound ::= expression\n' | |
| 7703 ' upper_bound ::= expression\n' | |
| 7704 ' stride ::= expression\n' | |
| 7705 '\n' | |
| 7706 'There is ambiguity in the formal syntax here: anything that ' | |
| 7707 'looks like\n' | |
| 7708 'an expression list also looks like a slice list, so any ' | |
| 7709 'subscription\n' | |
| 7710 'can be interpreted as a slicing. Rather than further ' | |
| 7711 'complicating the\n' | |
| 7712 'syntax, this is disambiguated by defining that in this case the\n' | |
| 7713 'interpretation as a subscription takes priority over the\n' | |
| 7714 'interpretation as a slicing (this is the case if the slice list\n' | |
| 7715 'contains no proper slice).\n' | |
| 7716 '\n' | |
| 7717 'The semantics for a slicing are as follows. The primary is ' | |
| 7718 'indexed\n' | |
| 7719 '(using the same "__getitem__()" method as normal subscription) ' | |
| 7720 'with a\n' | |
| 7721 'key that is constructed from the slice list, as follows. If the ' | |
| 7722 'slice\n' | |
| 7723 'list contains at least one comma, the key is a tuple containing ' | |
| 7724 'the\n' | |
| 7725 'conversion of the slice items; otherwise, the conversion of the ' | |
| 7726 'lone\n' | |
| 7727 'slice item is the key. The conversion of a slice item that is ' | |
| 7728 'an\n' | |
| 7729 'expression is that expression. The conversion of a proper slice ' | |
| 7730 'is a\n' | |
| 7731 'slice object (see section The standard type hierarchy) whose ' | |
| 7732 '"start",\n' | |
| 7733 '"stop" and "step" attributes are the values of the expressions ' | |
| 7734 'given\n' | |
| 7735 'as lower bound, upper bound and stride, respectively, ' | |
| 7736 'substituting\n' | |
| 7737 '"None" for missing expressions.\n', | |
| 7738 'specialattrs': 'Special Attributes\n' | |
| 7739 '******************\n' | |
| 7740 '\n' | |
| 7741 'The implementation adds a few special read-only attributes ' | |
| 7742 'to several\n' | |
| 7743 'object types, where they are relevant. Some of these are ' | |
| 7744 'not reported\n' | |
| 7745 'by the "dir()" built-in function.\n' | |
| 7746 '\n' | |
| 7747 'object.__dict__\n' | |
| 7748 '\n' | |
| 7749 ' A dictionary or other mapping object used to store an ' | |
| 7750 'object’s\n' | |
| 7751 ' (writable) attributes.\n' | |
| 7752 '\n' | |
| 7753 'instance.__class__\n' | |
| 7754 '\n' | |
| 7755 ' The class to which a class instance belongs.\n' | |
| 7756 '\n' | |
| 7757 'class.__bases__\n' | |
| 7758 '\n' | |
| 7759 ' The tuple of base classes of a class object.\n' | |
| 7760 '\n' | |
| 7761 'definition.__name__\n' | |
| 7762 '\n' | |
| 7763 ' The name of the class, function, method, descriptor, or ' | |
| 7764 'generator\n' | |
| 7765 ' instance.\n' | |
| 7766 '\n' | |
| 7767 'definition.__qualname__\n' | |
| 7768 '\n' | |
| 7769 ' The *qualified name* of the class, function, method, ' | |
| 7770 'descriptor, or\n' | |
| 7771 ' generator instance.\n' | |
| 7772 '\n' | |
| 7773 ' New in version 3.3.\n' | |
| 7774 '\n' | |
| 7775 'class.__mro__\n' | |
| 7776 '\n' | |
| 7777 ' This attribute is a tuple of classes that are considered ' | |
| 7778 'when\n' | |
| 7779 ' looking for base classes during method resolution.\n' | |
| 7780 '\n' | |
| 7781 'class.mro()\n' | |
| 7782 '\n' | |
| 7783 ' This method can be overridden by a metaclass to customize ' | |
| 7784 'the\n' | |
| 7785 ' method resolution order for its instances. It is called ' | |
| 7786 'at class\n' | |
| 7787 ' instantiation, and its result is stored in "__mro__".\n' | |
| 7788 '\n' | |
| 7789 'class.__subclasses__()\n' | |
| 7790 '\n' | |
| 7791 ' Each class keeps a list of weak references to its ' | |
| 7792 'immediate\n' | |
| 7793 ' subclasses. This method returns a list of all those ' | |
| 7794 'references\n' | |
| 7795 ' still alive. Example:\n' | |
| 7796 '\n' | |
| 7797 ' >>> int.__subclasses__()\n' | |
| 7798 " [<class 'bool'>]\n" | |
| 7799 '\n' | |
| 7800 '-[ Footnotes ]-\n' | |
| 7801 '\n' | |
| 7802 '[1] Additional information on these special methods may be ' | |
| 7803 'found\n' | |
| 7804 ' in the Python Reference Manual (Basic customization).\n' | |
| 7805 '\n' | |
| 7806 '[2] As a consequence, the list "[1, 2]" is considered equal ' | |
| 7807 'to\n' | |
| 7808 ' "[1.0, 2.0]", and similarly for tuples.\n' | |
| 7809 '\n' | |
| 7810 '[3] They must have since the parser can’t tell the type of ' | |
| 7811 'the\n' | |
| 7812 ' operands.\n' | |
| 7813 '\n' | |
| 7814 '[4] Cased characters are those with general category ' | |
| 7815 'property\n' | |
| 7816 ' being one of “Lu” (Letter, uppercase), “Ll” (Letter, ' | |
| 7817 'lowercase),\n' | |
| 7818 ' or “Lt” (Letter, titlecase).\n' | |
| 7819 '\n' | |
| 7820 '[5] To format only a tuple you should therefore provide a\n' | |
| 7821 ' singleton tuple whose only element is the tuple to be ' | |
| 7822 'formatted.\n', | |
| 7823 'specialnames': 'Special method names\n' | |
| 7824 '********************\n' | |
| 7825 '\n' | |
| 7826 'A class can implement certain operations that are invoked by ' | |
| 7827 'special\n' | |
| 7828 'syntax (such as arithmetic operations or subscripting and ' | |
| 7829 'slicing) by\n' | |
| 7830 'defining methods with special names. This is Python’s ' | |
| 7831 'approach to\n' | |
| 7832 '*operator overloading*, allowing classes to define their own ' | |
| 7833 'behavior\n' | |
| 7834 'with respect to language operators. For instance, if a ' | |
| 7835 'class defines\n' | |
| 7836 'a method named "__getitem__()", and "x" is an instance of ' | |
| 7837 'this class,\n' | |
| 7838 'then "x[i]" is roughly equivalent to "type(x).__getitem__(x, ' | |
| 7839 'i)".\n' | |
| 7840 'Except where mentioned, attempts to execute an operation ' | |
| 7841 'raise an\n' | |
| 7842 'exception when no appropriate method is defined (typically\n' | |
| 7843 '"AttributeError" or "TypeError").\n' | |
| 7844 '\n' | |
| 7845 'Setting a special method to "None" indicates that the ' | |
| 7846 'corresponding\n' | |
| 7847 'operation is not available. For example, if a class sets ' | |
| 7848 '"__iter__()"\n' | |
| 7849 'to "None", the class is not iterable, so calling "iter()" on ' | |
| 7850 'its\n' | |
| 7851 'instances will raise a "TypeError" (without falling back to\n' | |
| 7852 '"__getitem__()"). [2]\n' | |
| 7853 '\n' | |
| 7854 'When implementing a class that emulates any built-in type, ' | |
| 7855 'it is\n' | |
| 7856 'important that the emulation only be implemented to the ' | |
| 7857 'degree that it\n' | |
| 7858 'makes sense for the object being modelled. For example, ' | |
| 7859 'some\n' | |
| 7860 'sequences may work well with retrieval of individual ' | |
| 7861 'elements, but\n' | |
| 7862 'extracting a slice may not make sense. (One example of this ' | |
| 7863 'is the\n' | |
| 7864 '"NodeList" interface in the W3C’s Document Object Model.)\n' | |
| 7865 '\n' | |
| 7866 '\n' | |
| 7867 'Basic customization\n' | |
| 7868 '===================\n' | |
| 7869 '\n' | |
| 7870 'object.__new__(cls[, ...])\n' | |
| 7871 '\n' | |
| 7872 ' Called to create a new instance of class *cls*. ' | |
| 7873 '"__new__()" is a\n' | |
| 7874 ' static method (special-cased so you need not declare it ' | |
| 7875 'as such)\n' | |
| 7876 ' that takes the class of which an instance was requested ' | |
| 7877 'as its\n' | |
| 7878 ' first argument. The remaining arguments are those passed ' | |
| 7879 'to the\n' | |
| 7880 ' object constructor expression (the call to the class). ' | |
| 7881 'The return\n' | |
| 7882 ' value of "__new__()" should be the new object instance ' | |
| 7883 '(usually an\n' | |
| 7884 ' instance of *cls*).\n' | |
| 7885 '\n' | |
| 7886 ' Typical implementations create a new instance of the ' | |
| 7887 'class by\n' | |
| 7888 ' invoking the superclass’s "__new__()" method using\n' | |
| 7889 ' "super().__new__(cls[, ...])" with appropriate arguments ' | |
| 7890 'and then\n' | |
| 7891 ' modifying the newly-created instance as necessary before ' | |
| 7892 'returning\n' | |
| 7893 ' it.\n' | |
| 7894 '\n' | |
| 7895 ' If "__new__()" is invoked during object construction and ' | |
| 7896 'it returns\n' | |
| 7897 ' an instance or subclass of *cls*, then the new ' | |
| 7898 'instance’s\n' | |
| 7899 ' "__init__()" method will be invoked like "__init__(self[, ' | |
| 7900 '...])",\n' | |
| 7901 ' where *self* is the new instance and the remaining ' | |
| 7902 'arguments are\n' | |
| 7903 ' the same as were passed to the object constructor.\n' | |
| 7904 '\n' | |
| 7905 ' If "__new__()" does not return an instance of *cls*, then ' | |
| 7906 'the new\n' | |
| 7907 ' instance’s "__init__()" method will not be invoked.\n' | |
| 7908 '\n' | |
| 7909 ' "__new__()" is intended mainly to allow subclasses of ' | |
| 7910 'immutable\n' | |
| 7911 ' types (like int, str, or tuple) to customize instance ' | |
| 7912 'creation. It\n' | |
| 7913 ' is also commonly overridden in custom metaclasses in ' | |
| 7914 'order to\n' | |
| 7915 ' customize class creation.\n' | |
| 7916 '\n' | |
| 7917 'object.__init__(self[, ...])\n' | |
| 7918 '\n' | |
| 7919 ' Called after the instance has been created (by ' | |
| 7920 '"__new__()"), but\n' | |
| 7921 ' before it is returned to the caller. The arguments are ' | |
| 7922 'those\n' | |
| 7923 ' passed to the class constructor expression. If a base ' | |
| 7924 'class has an\n' | |
| 7925 ' "__init__()" method, the derived class’s "__init__()" ' | |
| 7926 'method, if\n' | |
| 7927 ' any, must explicitly call it to ensure proper ' | |
| 7928 'initialization of the\n' | |
| 7929 ' base class part of the instance; for example:\n' | |
| 7930 ' "super().__init__([args...])".\n' | |
| 7931 '\n' | |
| 7932 ' Because "__new__()" and "__init__()" work together in ' | |
| 7933 'constructing\n' | |
| 7934 ' objects ("__new__()" to create it, and "__init__()" to ' | |
| 7935 'customize\n' | |
| 7936 ' it), no non-"None" value may be returned by "__init__()"; ' | |
| 7937 'doing so\n' | |
| 7938 ' will cause a "TypeError" to be raised at runtime.\n' | |
| 7939 '\n' | |
| 7940 'object.__del__(self)\n' | |
| 7941 '\n' | |
| 7942 ' Called when the instance is about to be destroyed. This ' | |
| 7943 'is also\n' | |
| 7944 ' called a finalizer or (improperly) a destructor. If a ' | |
| 7945 'base class\n' | |
| 7946 ' has a "__del__()" method, the derived class’s "__del__()" ' | |
| 7947 'method,\n' | |
| 7948 ' if any, must explicitly call it to ensure proper deletion ' | |
| 7949 'of the\n' | |
| 7950 ' base class part of the instance.\n' | |
| 7951 '\n' | |
| 7952 ' It is possible (though not recommended!) for the ' | |
| 7953 '"__del__()" method\n' | |
| 7954 ' to postpone destruction of the instance by creating a new ' | |
| 7955 'reference\n' | |
| 7956 ' to it. This is called object *resurrection*. It is\n' | |
| 7957 ' implementation-dependent whether "__del__()" is called a ' | |
| 7958 'second\n' | |
| 7959 ' time when a resurrected object is about to be destroyed; ' | |
| 7960 'the\n' | |
| 7961 ' current *CPython* implementation only calls it once.\n' | |
| 7962 '\n' | |
| 7963 ' It is not guaranteed that "__del__()" methods are called ' | |
| 7964 'for\n' | |
| 7965 ' objects that still exist when the interpreter exits.\n' | |
| 7966 '\n' | |
| 7967 ' Note: "del x" doesn’t directly call "x.__del__()" — the ' | |
| 7968 'former\n' | |
| 7969 ' decrements the reference count for "x" by one, and the ' | |
| 7970 'latter is\n' | |
| 7971 ' only called when "x"’s reference count reaches zero.\n' | |
| 7972 '\n' | |
| 7973 ' **CPython implementation detail:** It is possible for a ' | |
| 7974 'reference\n' | |
| 7975 ' cycle to prevent the reference count of an object from ' | |
| 7976 'going to\n' | |
| 7977 ' zero. In this case, the cycle will be later detected and ' | |
| 7978 'deleted\n' | |
| 7979 ' by the *cyclic garbage collector*. A common cause of ' | |
| 7980 'reference\n' | |
| 7981 ' cycles is when an exception has been caught in a local ' | |
| 7982 'variable.\n' | |
| 7983 ' The frame’s locals then reference the exception, which ' | |
| 7984 'references\n' | |
| 7985 ' its own traceback, which references the locals of all ' | |
| 7986 'frames caught\n' | |
| 7987 ' in the traceback.\n' | |
| 7988 '\n' | |
| 7989 ' See also: Documentation for the "gc" module.\n' | |
| 7990 '\n' | |
| 7991 ' Warning: Due to the precarious circumstances under which\n' | |
| 7992 ' "__del__()" methods are invoked, exceptions that occur ' | |
| 7993 'during\n' | |
| 7994 ' their execution are ignored, and a warning is printed ' | |
| 7995 'to\n' | |
| 7996 ' "sys.stderr" instead. In particular:\n' | |
| 7997 '\n' | |
| 7998 ' * "__del__()" can be invoked when arbitrary code is ' | |
| 7999 'being\n' | |
| 8000 ' executed, including from any arbitrary thread. If ' | |
| 8001 '"__del__()"\n' | |
| 8002 ' needs to take a lock or invoke any other blocking ' | |
| 8003 'resource, it\n' | |
| 8004 ' may deadlock as the resource may already be taken by ' | |
| 8005 'the code\n' | |
| 8006 ' that gets interrupted to execute "__del__()".\n' | |
| 8007 '\n' | |
| 8008 ' * "__del__()" can be executed during interpreter ' | |
| 8009 'shutdown. As\n' | |
| 8010 ' a consequence, the global variables it needs to ' | |
| 8011 'access\n' | |
| 8012 ' (including other modules) may already have been ' | |
| 8013 'deleted or set\n' | |
| 8014 ' to "None". Python guarantees that globals whose name ' | |
| 8015 'begins\n' | |
| 8016 ' with a single underscore are deleted from their ' | |
| 8017 'module before\n' | |
| 8018 ' other globals are deleted; if no other references to ' | |
| 8019 'such\n' | |
| 8020 ' globals exist, this may help in assuring that ' | |
| 8021 'imported modules\n' | |
| 8022 ' are still available at the time when the "__del__()" ' | |
| 8023 'method is\n' | |
| 8024 ' called.\n' | |
| 8025 '\n' | |
| 8026 'object.__repr__(self)\n' | |
| 8027 '\n' | |
| 8028 ' Called by the "repr()" built-in function to compute the ' | |
| 8029 '“official”\n' | |
| 8030 ' string representation of an object. If at all possible, ' | |
| 8031 'this\n' | |
| 8032 ' should look like a valid Python expression that could be ' | |
| 8033 'used to\n' | |
| 8034 ' recreate an object with the same value (given an ' | |
| 8035 'appropriate\n' | |
| 8036 ' environment). If this is not possible, a string of the ' | |
| 8037 'form\n' | |
| 8038 ' "<...some useful description...>" should be returned. The ' | |
| 8039 'return\n' | |
| 8040 ' value must be a string object. If a class defines ' | |
| 8041 '"__repr__()" but\n' | |
| 8042 ' not "__str__()", then "__repr__()" is also used when an ' | |
| 8043 '“informal”\n' | |
| 8044 ' string representation of instances of that class is ' | |
| 8045 'required.\n' | |
| 8046 '\n' | |
| 8047 ' This is typically used for debugging, so it is important ' | |
| 8048 'that the\n' | |
| 8049 ' representation is information-rich and unambiguous.\n' | |
| 8050 '\n' | |
| 8051 'object.__str__(self)\n' | |
| 8052 '\n' | |
| 8053 ' Called by "str(object)" and the built-in functions ' | |
| 8054 '"format()" and\n' | |
| 8055 ' "print()" to compute the “informal” or nicely printable ' | |
| 8056 'string\n' | |
| 8057 ' representation of an object. The return value must be a ' | |
| 8058 'string\n' | |
| 8059 ' object.\n' | |
| 8060 '\n' | |
| 8061 ' This method differs from "object.__repr__()" in that ' | |
| 8062 'there is no\n' | |
| 8063 ' expectation that "__str__()" return a valid Python ' | |
| 8064 'expression: a\n' | |
| 8065 ' more convenient or concise representation can be used.\n' | |
| 8066 '\n' | |
| 8067 ' The default implementation defined by the built-in type ' | |
| 8068 '"object"\n' | |
| 8069 ' calls "object.__repr__()".\n' | |
| 8070 '\n' | |
| 8071 'object.__bytes__(self)\n' | |
| 8072 '\n' | |
| 8073 ' Called by bytes to compute a byte-string representation ' | |
| 8074 'of an\n' | |
| 8075 ' object. This should return a "bytes" object.\n' | |
| 8076 '\n' | |
| 8077 'object.__format__(self, format_spec)\n' | |
| 8078 '\n' | |
| 8079 ' Called by the "format()" built-in function, and by ' | |
| 8080 'extension,\n' | |
| 8081 ' evaluation of formatted string literals and the ' | |
| 8082 '"str.format()"\n' | |
| 8083 ' method, to produce a “formatted” string representation of ' | |
| 8084 'an\n' | |
| 8085 ' object. The *format_spec* argument is a string that ' | |
| 8086 'contains a\n' | |
| 8087 ' description of the formatting options desired. The ' | |
| 8088 'interpretation\n' | |
| 8089 ' of the *format_spec* argument is up to the type ' | |
| 8090 'implementing\n' | |
| 8091 ' "__format__()", however most classes will either ' | |
| 8092 'delegate\n' | |
| 8093 ' formatting to one of the built-in types, or use a ' | |
| 8094 'similar\n' | |
| 8095 ' formatting option syntax.\n' | |
| 8096 '\n' | |
| 8097 ' See Format Specification Mini-Language for a description ' | |
| 8098 'of the\n' | |
| 8099 ' standard formatting syntax.\n' | |
| 8100 '\n' | |
| 8101 ' The return value must be a string object.\n' | |
| 8102 '\n' | |
| 8103 ' Changed in version 3.4: The __format__ method of "object" ' | |
| 8104 'itself\n' | |
| 8105 ' raises a "TypeError" if passed any non-empty string.\n' | |
| 8106 '\n' | |
| 8107 ' Changed in version 3.7: "object.__format__(x, \'\')" is ' | |
| 8108 'now\n' | |
| 8109 ' equivalent to "str(x)" rather than "format(str(self), ' | |
| 8110 '\'\')".\n' | |
| 8111 '\n' | |
| 8112 'object.__lt__(self, other)\n' | |
| 8113 'object.__le__(self, other)\n' | |
| 8114 'object.__eq__(self, other)\n' | |
| 8115 'object.__ne__(self, other)\n' | |
| 8116 'object.__gt__(self, other)\n' | |
| 8117 'object.__ge__(self, other)\n' | |
| 8118 '\n' | |
| 8119 ' These are the so-called “rich comparison” methods. The\n' | |
| 8120 ' correspondence between operator symbols and method names ' | |
| 8121 'is as\n' | |
| 8122 ' follows: "x<y" calls "x.__lt__(y)", "x<=y" calls ' | |
| 8123 '"x.__le__(y)",\n' | |
| 8124 ' "x==y" calls "x.__eq__(y)", "x!=y" calls "x.__ne__(y)", ' | |
| 8125 '"x>y" calls\n' | |
| 8126 ' "x.__gt__(y)", and "x>=y" calls "x.__ge__(y)".\n' | |
| 8127 '\n' | |
| 8128 ' A rich comparison method may return the singleton ' | |
| 8129 '"NotImplemented"\n' | |
| 8130 ' if it does not implement the operation for a given pair ' | |
| 8131 'of\n' | |
| 8132 ' arguments. By convention, "False" and "True" are returned ' | |
| 8133 'for a\n' | |
| 8134 ' successful comparison. However, these methods can return ' | |
| 8135 'any value,\n' | |
| 8136 ' so if the comparison operator is used in a Boolean ' | |
| 8137 'context (e.g.,\n' | |
| 8138 ' in the condition of an "if" statement), Python will call ' | |
| 8139 '"bool()"\n' | |
| 8140 ' on the value to determine if the result is true or ' | |
| 8141 'false.\n' | |
| 8142 '\n' | |
| 8143 ' By default, "__ne__()" delegates to "__eq__()" and ' | |
| 8144 'inverts the\n' | |
| 8145 ' result unless it is "NotImplemented". There are no other ' | |
| 8146 'implied\n' | |
| 8147 ' relationships among the comparison operators, for ' | |
| 8148 'example, the\n' | |
| 8149 ' truth of "(x<y or x==y)" does not imply "x<=y". To ' | |
| 8150 'automatically\n' | |
| 8151 ' generate ordering operations from a single root ' | |
| 8152 'operation, see\n' | |
| 8153 ' "functools.total_ordering()".\n' | |
| 8154 '\n' | |
| 8155 ' See the paragraph on "__hash__()" for some important ' | |
| 8156 'notes on\n' | |
| 8157 ' creating *hashable* objects which support custom ' | |
| 8158 'comparison\n' | |
| 8159 ' operations and are usable as dictionary keys.\n' | |
| 8160 '\n' | |
| 8161 ' There are no swapped-argument versions of these methods ' | |
| 8162 '(to be used\n' | |
| 8163 ' when the left argument does not support the operation but ' | |
| 8164 'the right\n' | |
| 8165 ' argument does); rather, "__lt__()" and "__gt__()" are ' | |
| 8166 'each other’s\n' | |
| 8167 ' reflection, "__le__()" and "__ge__()" are each other’s ' | |
| 8168 'reflection,\n' | |
| 8169 ' and "__eq__()" and "__ne__()" are their own reflection. ' | |
| 8170 'If the\n' | |
| 8171 ' operands are of different types, and right operand’s type ' | |
| 8172 'is a\n' | |
| 8173 ' direct or indirect subclass of the left operand’s type, ' | |
| 8174 'the\n' | |
| 8175 ' reflected method of the right operand has priority, ' | |
| 8176 'otherwise the\n' | |
| 8177 ' left operand’s method has priority. Virtual subclassing ' | |
| 8178 'is not\n' | |
| 8179 ' considered.\n' | |
| 8180 '\n' | |
| 8181 'object.__hash__(self)\n' | |
| 8182 '\n' | |
| 8183 ' Called by built-in function "hash()" and for operations ' | |
| 8184 'on members\n' | |
| 8185 ' of hashed collections including "set", "frozenset", and ' | |
| 8186 '"dict".\n' | |
| 8187 ' "__hash__()" should return an integer. The only required ' | |
| 8188 'property\n' | |
| 8189 ' is that objects which compare equal have the same hash ' | |
| 8190 'value; it is\n' | |
| 8191 ' advised to mix together the hash values of the components ' | |
| 8192 'of the\n' | |
| 8193 ' object that also play a part in comparison of objects by ' | |
| 8194 'packing\n' | |
| 8195 ' them into a tuple and hashing the tuple. Example:\n' | |
| 8196 '\n' | |
| 8197 ' def __hash__(self):\n' | |
| 8198 ' return hash((self.name, self.nick, self.color))\n' | |
| 8199 '\n' | |
| 8200 ' Note: "hash()" truncates the value returned from an ' | |
| 8201 'object’s\n' | |
| 8202 ' custom "__hash__()" method to the size of a ' | |
| 8203 '"Py_ssize_t". This\n' | |
| 8204 ' is typically 8 bytes on 64-bit builds and 4 bytes on ' | |
| 8205 '32-bit\n' | |
| 8206 ' builds. If an object’s "__hash__()" must interoperate ' | |
| 8207 'on builds\n' | |
| 8208 ' of different bit sizes, be sure to check the width on ' | |
| 8209 'all\n' | |
| 8210 ' supported builds. An easy way to do this is with ' | |
| 8211 '"python -c\n' | |
| 8212 ' "import sys; print(sys.hash_info.width)"".\n' | |
| 8213 '\n' | |
| 8214 ' If a class does not define an "__eq__()" method it should ' | |
| 8215 'not\n' | |
| 8216 ' define a "__hash__()" operation either; if it defines ' | |
| 8217 '"__eq__()"\n' | |
| 8218 ' but not "__hash__()", its instances will not be usable as ' | |
| 8219 'items in\n' | |
| 8220 ' hashable collections. If a class defines mutable objects ' | |
| 8221 'and\n' | |
| 8222 ' implements an "__eq__()" method, it should not implement\n' | |
| 8223 ' "__hash__()", since the implementation of hashable ' | |
| 8224 'collections\n' | |
| 8225 ' requires that a key’s hash value is immutable (if the ' | |
| 8226 'object’s hash\n' | |
| 8227 ' value changes, it will be in the wrong hash bucket).\n' | |
| 8228 '\n' | |
| 8229 ' User-defined classes have "__eq__()" and "__hash__()" ' | |
| 8230 'methods by\n' | |
| 8231 ' default; with them, all objects compare unequal (except ' | |
| 8232 'with\n' | |
| 8233 ' themselves) and "x.__hash__()" returns an appropriate ' | |
| 8234 'value such\n' | |
| 8235 ' that "x == y" implies both that "x is y" and "hash(x) == ' | |
| 8236 'hash(y)".\n' | |
| 8237 '\n' | |
| 8238 ' A class that overrides "__eq__()" and does not define ' | |
| 8239 '"__hash__()"\n' | |
| 8240 ' will have its "__hash__()" implicitly set to "None". ' | |
| 8241 'When the\n' | |
| 8242 ' "__hash__()" method of a class is "None", instances of ' | |
| 8243 'the class\n' | |
| 8244 ' will raise an appropriate "TypeError" when a program ' | |
| 8245 'attempts to\n' | |
| 8246 ' retrieve their hash value, and will also be correctly ' | |
| 8247 'identified as\n' | |
| 8248 ' unhashable when checking "isinstance(obj,\n' | |
| 8249 ' collections.abc.Hashable)".\n' | |
| 8250 '\n' | |
| 8251 ' If a class that overrides "__eq__()" needs to retain the\n' | |
| 8252 ' implementation of "__hash__()" from a parent class, the ' | |
| 8253 'interpreter\n' | |
| 8254 ' must be told this explicitly by setting "__hash__ =\n' | |
| 8255 ' <ParentClass>.__hash__".\n' | |
| 8256 '\n' | |
| 8257 ' If a class that does not override "__eq__()" wishes to ' | |
| 8258 'suppress\n' | |
| 8259 ' hash support, it should include "__hash__ = None" in the ' | |
| 8260 'class\n' | |
| 8261 ' definition. A class which defines its own "__hash__()" ' | |
| 8262 'that\n' | |
| 8263 ' explicitly raises a "TypeError" would be incorrectly ' | |
| 8264 'identified as\n' | |
| 8265 ' hashable by an "isinstance(obj, ' | |
| 8266 'collections.abc.Hashable)" call.\n' | |
| 8267 '\n' | |
| 8268 ' Note: By default, the "__hash__()" values of str and ' | |
| 8269 'bytes\n' | |
| 8270 ' objects are “salted” with an unpredictable random ' | |
| 8271 'value.\n' | |
| 8272 ' Although they remain constant within an individual ' | |
| 8273 'Python\n' | |
| 8274 ' process, they are not predictable between repeated ' | |
| 8275 'invocations of\n' | |
| 8276 ' Python.This is intended to provide protection against a ' | |
| 8277 'denial-\n' | |
| 8278 ' of-service caused by carefully-chosen inputs that ' | |
| 8279 'exploit the\n' | |
| 8280 ' worst case performance of a dict insertion, O(n^2) ' | |
| 8281 'complexity.\n' | |
| 8282 ' See http://www.ocert.org/advisories/ocert-2011-003.html ' | |
| 8283 'for\n' | |
| 8284 ' details.Changing hash values affects the iteration ' | |
| 8285 'order of sets.\n' | |
| 8286 ' Python has never made guarantees about this ordering ' | |
| 8287 '(and it\n' | |
| 8288 ' typically varies between 32-bit and 64-bit builds).See ' | |
| 8289 'also\n' | |
| 8290 ' "PYTHONHASHSEED".\n' | |
| 8291 '\n' | |
| 8292 ' Changed in version 3.3: Hash randomization is enabled by ' | |
| 8293 'default.\n' | |
| 8294 '\n' | |
| 8295 'object.__bool__(self)\n' | |
| 8296 '\n' | |
| 8297 ' Called to implement truth value testing and the built-in ' | |
| 8298 'operation\n' | |
| 8299 ' "bool()"; should return "False" or "True". When this ' | |
| 8300 'method is not\n' | |
| 8301 ' defined, "__len__()" is called, if it is defined, and the ' | |
| 8302 'object is\n' | |
| 8303 ' considered true if its result is nonzero. If a class ' | |
| 8304 'defines\n' | |
| 8305 ' neither "__len__()" nor "__bool__()", all its instances ' | |
| 8306 'are\n' | |
| 8307 ' considered true.\n' | |
| 8308 '\n' | |
| 8309 '\n' | |
| 8310 'Customizing attribute access\n' | |
| 8311 '============================\n' | |
| 8312 '\n' | |
| 8313 'The following methods can be defined to customize the ' | |
| 8314 'meaning of\n' | |
| 8315 'attribute access (use of, assignment to, or deletion of ' | |
| 8316 '"x.name") for\n' | |
| 8317 'class instances.\n' | |
| 8318 '\n' | |
| 8319 'object.__getattr__(self, name)\n' | |
| 8320 '\n' | |
| 8321 ' Called when the default attribute access fails with an\n' | |
| 8322 ' "AttributeError" (either "__getattribute__()" raises an\n' | |
| 8323 ' "AttributeError" because *name* is not an instance ' | |
| 8324 'attribute or an\n' | |
| 8325 ' attribute in the class tree for "self"; or "__get__()" of ' | |
| 8326 'a *name*\n' | |
| 8327 ' property raises "AttributeError"). This method should ' | |
| 8328 'either\n' | |
| 8329 ' return the (computed) attribute value or raise an ' | |
| 8330 '"AttributeError"\n' | |
| 8331 ' exception.\n' | |
| 8332 '\n' | |
| 8333 ' Note that if the attribute is found through the normal ' | |
| 8334 'mechanism,\n' | |
| 8335 ' "__getattr__()" is not called. (This is an intentional ' | |
| 8336 'asymmetry\n' | |
| 8337 ' between "__getattr__()" and "__setattr__()".) This is ' | |
| 8338 'done both for\n' | |
| 8339 ' efficiency reasons and because otherwise "__getattr__()" ' | |
| 8340 'would have\n' | |
| 8341 ' no way to access other attributes of the instance. Note ' | |
| 8342 'that at\n' | |
| 8343 ' least for instance variables, you can fake total control ' | |
| 8344 'by not\n' | |
| 8345 ' inserting any values in the instance attribute dictionary ' | |
| 8346 '(but\n' | |
| 8347 ' instead inserting them in another object). See the\n' | |
| 8348 ' "__getattribute__()" method below for a way to actually ' | |
| 8349 'get total\n' | |
| 8350 ' control over attribute access.\n' | |
| 8351 '\n' | |
| 8352 'object.__getattribute__(self, name)\n' | |
| 8353 '\n' | |
| 8354 ' Called unconditionally to implement attribute accesses ' | |
| 8355 'for\n' | |
| 8356 ' instances of the class. If the class also defines ' | |
| 8357 '"__getattr__()",\n' | |
| 8358 ' the latter will not be called unless "__getattribute__()" ' | |
| 8359 'either\n' | |
| 8360 ' calls it explicitly or raises an "AttributeError". This ' | |
| 8361 'method\n' | |
| 8362 ' should return the (computed) attribute value or raise an\n' | |
| 8363 ' "AttributeError" exception. In order to avoid infinite ' | |
| 8364 'recursion in\n' | |
| 8365 ' this method, its implementation should always call the ' | |
| 8366 'base class\n' | |
| 8367 ' method with the same name to access any attributes it ' | |
| 8368 'needs, for\n' | |
| 8369 ' example, "object.__getattribute__(self, name)".\n' | |
| 8370 '\n' | |
| 8371 ' Note: This method may still be bypassed when looking up ' | |
| 8372 'special\n' | |
| 8373 ' methods as the result of implicit invocation via ' | |
| 8374 'language syntax\n' | |
| 8375 ' or built-in functions. See Special method lookup.\n' | |
| 8376 '\n' | |
| 8377 'object.__setattr__(self, name, value)\n' | |
| 8378 '\n' | |
| 8379 ' Called when an attribute assignment is attempted. This ' | |
| 8380 'is called\n' | |
| 8381 ' instead of the normal mechanism (i.e. store the value in ' | |
| 8382 'the\n' | |
| 8383 ' instance dictionary). *name* is the attribute name, ' | |
| 8384 '*value* is the\n' | |
| 8385 ' value to be assigned to it.\n' | |
| 8386 '\n' | |
| 8387 ' If "__setattr__()" wants to assign to an instance ' | |
| 8388 'attribute, it\n' | |
| 8389 ' should call the base class method with the same name, for ' | |
| 8390 'example,\n' | |
| 8391 ' "object.__setattr__(self, name, value)".\n' | |
| 8392 '\n' | |
| 8393 'object.__delattr__(self, name)\n' | |
| 8394 '\n' | |
| 8395 ' Like "__setattr__()" but for attribute deletion instead ' | |
| 8396 'of\n' | |
| 8397 ' assignment. This should only be implemented if "del ' | |
| 8398 'obj.name" is\n' | |
| 8399 ' meaningful for the object.\n' | |
| 8400 '\n' | |
| 8401 'object.__dir__(self)\n' | |
| 8402 '\n' | |
| 8403 ' Called when "dir()" is called on the object. A sequence ' | |
| 8404 'must be\n' | |
| 8405 ' returned. "dir()" converts the returned sequence to a ' | |
| 8406 'list and\n' | |
| 8407 ' sorts it.\n' | |
| 8408 '\n' | |
| 8409 '\n' | |
| 8410 'Customizing module attribute access\n' | |
| 8411 '-----------------------------------\n' | |
| 8412 '\n' | |
| 8413 'Special names "__getattr__" and "__dir__" can be also used ' | |
| 8414 'to\n' | |
| 8415 'customize access to module attributes. The "__getattr__" ' | |
| 8416 'function at\n' | |
| 8417 'the module level should accept one argument which is the ' | |
| 8418 'name of an\n' | |
| 8419 'attribute and return the computed value or raise an ' | |
| 8420 '"AttributeError".\n' | |
| 8421 'If an attribute is not found on a module object through the ' | |
| 8422 'normal\n' | |
| 8423 'lookup, i.e. "object.__getattribute__()", then "__getattr__" ' | |
| 8424 'is\n' | |
| 8425 'searched in the module "__dict__" before raising an ' | |
| 8426 '"AttributeError".\n' | |
| 8427 'If found, it is called with the attribute name and the ' | |
| 8428 'result is\n' | |
| 8429 'returned.\n' | |
| 8430 '\n' | |
| 8431 'The "__dir__" function should accept no arguments, and ' | |
| 8432 'return a\n' | |
| 8433 'sequence of strings that represents the names accessible on ' | |
| 8434 'module. If\n' | |
| 8435 'present, this function overrides the standard "dir()" search ' | |
| 8436 'on a\n' | |
| 8437 'module.\n' | |
| 8438 '\n' | |
| 8439 'For a more fine grained customization of the module behavior ' | |
| 8440 '(setting\n' | |
| 8441 'attributes, properties, etc.), one can set the "__class__" ' | |
| 8442 'attribute\n' | |
| 8443 'of a module object to a subclass of "types.ModuleType". For ' | |
| 8444 'example:\n' | |
| 8445 '\n' | |
| 8446 ' import sys\n' | |
| 8447 ' from types import ModuleType\n' | |
| 8448 '\n' | |
| 8449 ' class VerboseModule(ModuleType):\n' | |
| 8450 ' def __repr__(self):\n' | |
| 8451 " return f'Verbose {self.__name__}'\n" | |
| 8452 '\n' | |
| 8453 ' def __setattr__(self, attr, value):\n' | |
| 8454 " print(f'Setting {attr}...')\n" | |
| 8455 ' super().__setattr__(attr, value)\n' | |
| 8456 '\n' | |
| 8457 ' sys.modules[__name__].__class__ = VerboseModule\n' | |
| 8458 '\n' | |
| 8459 'Note: Defining module "__getattr__" and setting module ' | |
| 8460 '"__class__"\n' | |
| 8461 ' only affect lookups made using the attribute access syntax ' | |
| 8462 '–\n' | |
| 8463 ' directly accessing the module globals (whether by code ' | |
| 8464 'within the\n' | |
| 8465 ' module, or via a reference to the module’s globals ' | |
| 8466 'dictionary) is\n' | |
| 8467 ' unaffected.\n' | |
| 8468 '\n' | |
| 8469 'Changed in version 3.5: "__class__" module attribute is now ' | |
| 8470 'writable.\n' | |
| 8471 '\n' | |
| 8472 'New in version 3.7: "__getattr__" and "__dir__" module ' | |
| 8473 'attributes.\n' | |
| 8474 '\n' | |
| 8475 'See also:\n' | |
| 8476 '\n' | |
| 8477 ' **PEP 562** - Module __getattr__ and __dir__\n' | |
| 8478 ' Describes the "__getattr__" and "__dir__" functions on ' | |
| 8479 'modules.\n' | |
| 8480 '\n' | |
| 8481 '\n' | |
| 8482 'Implementing Descriptors\n' | |
| 8483 '------------------------\n' | |
| 8484 '\n' | |
| 8485 'The following methods only apply when an instance of the ' | |
| 8486 'class\n' | |
| 8487 'containing the method (a so-called *descriptor* class) ' | |
| 8488 'appears in an\n' | |
| 8489 '*owner* class (the descriptor must be in either the owner’s ' | |
| 8490 'class\n' | |
| 8491 'dictionary or in the class dictionary for one of its ' | |
| 8492 'parents). In the\n' | |
| 8493 'examples below, “the attribute” refers to the attribute ' | |
| 8494 'whose name is\n' | |
| 8495 'the key of the property in the owner class’ "__dict__".\n' | |
| 8496 '\n' | |
| 8497 'object.__get__(self, instance, owner=None)\n' | |
| 8498 '\n' | |
| 8499 ' Called to get the attribute of the owner class (class ' | |
| 8500 'attribute\n' | |
| 8501 ' access) or of an instance of that class (instance ' | |
| 8502 'attribute\n' | |
| 8503 ' access). The optional *owner* argument is the owner ' | |
| 8504 'class, while\n' | |
| 8505 ' *instance* is the instance that the attribute was ' | |
| 8506 'accessed through,\n' | |
| 8507 ' or "None" when the attribute is accessed through the ' | |
| 8508 '*owner*.\n' | |
| 8509 '\n' | |
| 8510 ' This method should return the computed attribute value or ' | |
| 8511 'raise an\n' | |
| 8512 ' "AttributeError" exception.\n' | |
| 8513 '\n' | |
| 8514 ' **PEP 252** specifies that "__get__()" is callable with ' | |
| 8515 'one or two\n' | |
| 8516 ' arguments. Python’s own built-in descriptors support ' | |
| 8517 'this\n' | |
| 8518 ' specification; however, it is likely that some ' | |
| 8519 'third-party tools\n' | |
| 8520 ' have descriptors that require both arguments. Python’s ' | |
| 8521 'own\n' | |
| 8522 ' "__getattribute__()" implementation always passes in both ' | |
| 8523 'arguments\n' | |
| 8524 ' whether they are required or not.\n' | |
| 8525 '\n' | |
| 8526 'object.__set__(self, instance, value)\n' | |
| 8527 '\n' | |
| 8528 ' Called to set the attribute on an instance *instance* of ' | |
| 8529 'the owner\n' | |
| 8530 ' class to a new value, *value*.\n' | |
| 8531 '\n' | |
| 8532 ' Note, adding "__set__()" or "__delete__()" changes the ' | |
| 8533 'kind of\n' | |
| 8534 ' descriptor to a “data descriptor”. See Invoking ' | |
| 8535 'Descriptors for\n' | |
| 8536 ' more details.\n' | |
| 8537 '\n' | |
| 8538 'object.__delete__(self, instance)\n' | |
| 8539 '\n' | |
| 8540 ' Called to delete the attribute on an instance *instance* ' | |
| 8541 'of the\n' | |
| 8542 ' owner class.\n' | |
| 8543 '\n' | |
| 8544 'object.__set_name__(self, owner, name)\n' | |
| 8545 '\n' | |
| 8546 ' Called at the time the owning class *owner* is created. ' | |
| 8547 'The\n' | |
| 8548 ' descriptor has been assigned to *name*.\n' | |
| 8549 '\n' | |
| 8550 ' Note: "__set_name__()" is only called implicitly as part ' | |
| 8551 'of the\n' | |
| 8552 ' "type" constructor, so it will need to be called ' | |
| 8553 'explicitly with\n' | |
| 8554 ' the appropriate parameters when a descriptor is added ' | |
| 8555 'to a class\n' | |
| 8556 ' after initial creation:\n' | |
| 8557 '\n' | |
| 8558 ' class A:\n' | |
| 8559 ' pass\n' | |
| 8560 ' descr = custom_descriptor()\n' | |
| 8561 ' A.attr = descr\n' | |
| 8562 " descr.__set_name__(A, 'attr')\n" | |
| 8563 '\n' | |
| 8564 ' See Creating the class object for more details.\n' | |
| 8565 '\n' | |
| 8566 ' New in version 3.6.\n' | |
| 8567 '\n' | |
| 8568 'The attribute "__objclass__" is interpreted by the "inspect" ' | |
| 8569 'module as\n' | |
| 8570 'specifying the class where this object was defined (setting ' | |
| 8571 'this\n' | |
| 8572 'appropriately can assist in runtime introspection of dynamic ' | |
| 8573 'class\n' | |
| 8574 'attributes). For callables, it may indicate that an instance ' | |
| 8575 'of the\n' | |
| 8576 'given type (or a subclass) is expected or required as the ' | |
| 8577 'first\n' | |
| 8578 'positional argument (for example, CPython sets this ' | |
| 8579 'attribute for\n' | |
| 8580 'unbound methods that are implemented in C).\n' | |
| 8581 '\n' | |
| 8582 '\n' | |
| 8583 'Invoking Descriptors\n' | |
| 8584 '--------------------\n' | |
| 8585 '\n' | |
| 8586 'In general, a descriptor is an object attribute with ' | |
| 8587 '“binding\n' | |
| 8588 'behavior”, one whose attribute access has been overridden by ' | |
| 8589 'methods\n' | |
| 8590 'in the descriptor protocol: "__get__()", "__set__()", and\n' | |
| 8591 '"__delete__()". If any of those methods are defined for an ' | |
| 8592 'object, it\n' | |
| 8593 'is said to be a descriptor.\n' | |
| 8594 '\n' | |
| 8595 'The default behavior for attribute access is to get, set, or ' | |
| 8596 'delete\n' | |
| 8597 'the attribute from an object’s dictionary. For instance, ' | |
| 8598 '"a.x" has a\n' | |
| 8599 'lookup chain starting with "a.__dict__[\'x\']", then\n' | |
| 8600 '"type(a).__dict__[\'x\']", and continuing through the base ' | |
| 8601 'classes of\n' | |
| 8602 '"type(a)" excluding metaclasses.\n' | |
| 8603 '\n' | |
| 8604 'However, if the looked-up value is an object defining one of ' | |
| 8605 'the\n' | |
| 8606 'descriptor methods, then Python may override the default ' | |
| 8607 'behavior and\n' | |
| 8608 'invoke the descriptor method instead. Where this occurs in ' | |
| 8609 'the\n' | |
| 8610 'precedence chain depends on which descriptor methods were ' | |
| 8611 'defined and\n' | |
| 8612 'how they were called.\n' | |
| 8613 '\n' | |
| 8614 'The starting point for descriptor invocation is a binding, ' | |
| 8615 '"a.x". How\n' | |
| 8616 'the arguments are assembled depends on "a":\n' | |
| 8617 '\n' | |
| 8618 'Direct Call\n' | |
| 8619 ' The simplest and least common call is when user code ' | |
| 8620 'directly\n' | |
| 8621 ' invokes a descriptor method: "x.__get__(a)".\n' | |
| 8622 '\n' | |
| 8623 'Instance Binding\n' | |
| 8624 ' If binding to an object instance, "a.x" is transformed ' | |
| 8625 'into the\n' | |
| 8626 ' call: "type(a).__dict__[\'x\'].__get__(a, type(a))".\n' | |
| 8627 '\n' | |
| 8628 'Class Binding\n' | |
| 8629 ' If binding to a class, "A.x" is transformed into the ' | |
| 8630 'call:\n' | |
| 8631 ' "A.__dict__[\'x\'].__get__(None, A)".\n' | |
| 8632 '\n' | |
| 8633 'Super Binding\n' | |
| 8634 ' If "a" is an instance of "super", then the binding ' | |
| 8635 '"super(B,\n' | |
| 8636 ' obj).m()" searches "obj.__class__.__mro__" for the base ' | |
| 8637 'class "A"\n' | |
| 8638 ' immediately preceding "B" and then invokes the descriptor ' | |
| 8639 'with the\n' | |
| 8640 ' call: "A.__dict__[\'m\'].__get__(obj, obj.__class__)".\n' | |
| 8641 '\n' | |
| 8642 'For instance bindings, the precedence of descriptor ' | |
| 8643 'invocation depends\n' | |
| 8644 'on the which descriptor methods are defined. A descriptor ' | |
| 8645 'can define\n' | |
| 8646 'any combination of "__get__()", "__set__()" and ' | |
| 8647 '"__delete__()". If it\n' | |
| 8648 'does not define "__get__()", then accessing the attribute ' | |
| 8649 'will return\n' | |
| 8650 'the descriptor object itself unless there is a value in the ' | |
| 8651 'object’s\n' | |
| 8652 'instance dictionary. If the descriptor defines "__set__()" ' | |
| 8653 'and/or\n' | |
| 8654 '"__delete__()", it is a data descriptor; if it defines ' | |
| 8655 'neither, it is\n' | |
| 8656 'a non-data descriptor. Normally, data descriptors define ' | |
| 8657 'both\n' | |
| 8658 '"__get__()" and "__set__()", while non-data descriptors have ' | |
| 8659 'just the\n' | |
| 8660 '"__get__()" method. Data descriptors with "__set__()" and ' | |
| 8661 '"__get__()"\n' | |
| 8662 'defined always override a redefinition in an instance ' | |
| 8663 'dictionary. In\n' | |
| 8664 'contrast, non-data descriptors can be overridden by ' | |
| 8665 'instances.\n' | |
| 8666 '\n' | |
| 8667 'Python methods (including "staticmethod()" and ' | |
| 8668 '"classmethod()") are\n' | |
| 8669 'implemented as non-data descriptors. Accordingly, instances ' | |
| 8670 'can\n' | |
| 8671 'redefine and override methods. This allows individual ' | |
| 8672 'instances to\n' | |
| 8673 'acquire behaviors that differ from other instances of the ' | |
| 8674 'same class.\n' | |
| 8675 '\n' | |
| 8676 'The "property()" function is implemented as a data ' | |
| 8677 'descriptor.\n' | |
| 8678 'Accordingly, instances cannot override the behavior of a ' | |
| 8679 'property.\n' | |
| 8680 '\n' | |
| 8681 '\n' | |
| 8682 '__slots__\n' | |
| 8683 '---------\n' | |
| 8684 '\n' | |
| 8685 '*__slots__* allow us to explicitly declare data members ' | |
| 8686 '(like\n' | |
| 8687 'properties) and deny the creation of *__dict__* and ' | |
| 8688 '*__weakref__*\n' | |
| 8689 '(unless explicitly declared in *__slots__* or available in a ' | |
| 8690 'parent.)\n' | |
| 8691 '\n' | |
| 8692 'The space saved over using *__dict__* can be significant. ' | |
| 8693 'Attribute\n' | |
| 8694 'lookup speed can be significantly improved as well.\n' | |
| 8695 '\n' | |
| 8696 'object.__slots__\n' | |
| 8697 '\n' | |
| 8698 ' This class variable can be assigned a string, iterable, ' | |
| 8699 'or sequence\n' | |
| 8700 ' of strings with variable names used by instances. ' | |
| 8701 '*__slots__*\n' | |
| 8702 ' reserves space for the declared variables and prevents ' | |
| 8703 'the\n' | |
| 8704 ' automatic creation of *__dict__* and *__weakref__* for ' | |
| 8705 'each\n' | |
| 8706 ' instance.\n' | |
| 8707 '\n' | |
| 8708 '\n' | |
| 8709 'Notes on using *__slots__*\n' | |
| 8710 '~~~~~~~~~~~~~~~~~~~~~~~~~~\n' | |
| 8711 '\n' | |
| 8712 '* When inheriting from a class without *__slots__*, the ' | |
| 8713 '*__dict__*\n' | |
| 8714 ' and *__weakref__* attribute of the instances will always ' | |
| 8715 'be\n' | |
| 8716 ' accessible.\n' | |
| 8717 '\n' | |
| 8718 '* Without a *__dict__* variable, instances cannot be ' | |
| 8719 'assigned new\n' | |
| 8720 ' variables not listed in the *__slots__* definition. ' | |
| 8721 'Attempts to\n' | |
| 8722 ' assign to an unlisted variable name raises ' | |
| 8723 '"AttributeError". If\n' | |
| 8724 ' dynamic assignment of new variables is desired, then add\n' | |
| 8725 ' "\'__dict__\'" to the sequence of strings in the ' | |
| 8726 '*__slots__*\n' | |
| 8727 ' declaration.\n' | |
| 8728 '\n' | |
| 8729 '* Without a *__weakref__* variable for each instance, ' | |
| 8730 'classes\n' | |
| 8731 ' defining *__slots__* do not support weak references to ' | |
| 8732 'its\n' | |
| 8733 ' instances. If weak reference support is needed, then add\n' | |
| 8734 ' "\'__weakref__\'" to the sequence of strings in the ' | |
| 8735 '*__slots__*\n' | |
| 8736 ' declaration.\n' | |
| 8737 '\n' | |
| 8738 '* *__slots__* are implemented at the class level by ' | |
| 8739 'creating\n' | |
| 8740 ' descriptors (Implementing Descriptors) for each variable ' | |
| 8741 'name. As a\n' | |
| 8742 ' result, class attributes cannot be used to set default ' | |
| 8743 'values for\n' | |
| 8744 ' instance variables defined by *__slots__*; otherwise, the ' | |
| 8745 'class\n' | |
| 8746 ' attribute would overwrite the descriptor assignment.\n' | |
| 8747 '\n' | |
| 8748 '* The action of a *__slots__* declaration is not limited to ' | |
| 8749 'the\n' | |
| 8750 ' class where it is defined. *__slots__* declared in ' | |
| 8751 'parents are\n' | |
| 8752 ' available in child classes. However, child subclasses will ' | |
| 8753 'get a\n' | |
| 8754 ' *__dict__* and *__weakref__* unless they also define ' | |
| 8755 '*__slots__*\n' | |
| 8756 ' (which should only contain names of any *additional* ' | |
| 8757 'slots).\n' | |
| 8758 '\n' | |
| 8759 '* If a class defines a slot also defined in a base class, ' | |
| 8760 'the\n' | |
| 8761 ' instance variable defined by the base class slot is ' | |
| 8762 'inaccessible\n' | |
| 8763 ' (except by retrieving its descriptor directly from the ' | |
| 8764 'base class).\n' | |
| 8765 ' This renders the meaning of the program undefined. In the ' | |
| 8766 'future, a\n' | |
| 8767 ' check may be added to prevent this.\n' | |
| 8768 '\n' | |
| 8769 '* Nonempty *__slots__* does not work for classes derived ' | |
| 8770 'from\n' | |
| 8771 ' “variable-length” built-in types such as "int", "bytes" ' | |
| 8772 'and "tuple".\n' | |
| 8773 '\n' | |
| 8774 '* Any non-string iterable may be assigned to *__slots__*. ' | |
| 8775 'Mappings\n' | |
| 8776 ' may also be used; however, in the future, special meaning ' | |
| 8777 'may be\n' | |
| 8778 ' assigned to the values corresponding to each key.\n' | |
| 8779 '\n' | |
| 8780 '* *__class__* assignment works only if both classes have the ' | |
| 8781 'same\n' | |
| 8782 ' *__slots__*.\n' | |
| 8783 '\n' | |
| 8784 '* Multiple inheritance with multiple slotted parent classes ' | |
| 8785 'can be\n' | |
| 8786 ' used, but only one parent is allowed to have attributes ' | |
| 8787 'created by\n' | |
| 8788 ' slots (the other bases must have empty slot layouts) - ' | |
| 8789 'violations\n' | |
| 8790 ' raise "TypeError".\n' | |
| 8791 '\n' | |
| 8792 '* If an iterator is used for *__slots__* then a descriptor ' | |
| 8793 'is\n' | |
| 8794 ' created for each of the iterator’s values. However, the ' | |
| 8795 '*__slots__*\n' | |
| 8796 ' attribute will be an empty iterator.\n' | |
| 8797 '\n' | |
| 8798 '\n' | |
| 8799 'Customizing class creation\n' | |
| 8800 '==========================\n' | |
| 8801 '\n' | |
| 8802 'Whenever a class inherits from another class, ' | |
| 8803 '*__init_subclass__* is\n' | |
| 8804 'called on that class. This way, it is possible to write ' | |
| 8805 'classes which\n' | |
| 8806 'change the behavior of subclasses. This is closely related ' | |
| 8807 'to class\n' | |
| 8808 'decorators, but where class decorators only affect the ' | |
| 8809 'specific class\n' | |
| 8810 'they’re applied to, "__init_subclass__" solely applies to ' | |
| 8811 'future\n' | |
| 8812 'subclasses of the class defining the method.\n' | |
| 8813 '\n' | |
| 8814 'classmethod object.__init_subclass__(cls)\n' | |
| 8815 '\n' | |
| 8816 ' This method is called whenever the containing class is ' | |
| 8817 'subclassed.\n' | |
| 8818 ' *cls* is then the new subclass. If defined as a normal ' | |
| 8819 'instance\n' | |
| 8820 ' method, this method is implicitly converted to a class ' | |
| 8821 'method.\n' | |
| 8822 '\n' | |
| 8823 ' Keyword arguments which are given to a new class are ' | |
| 8824 'passed to the\n' | |
| 8825 ' parent’s class "__init_subclass__". For compatibility ' | |
| 8826 'with other\n' | |
| 8827 ' classes using "__init_subclass__", one should take out ' | |
| 8828 'the needed\n' | |
| 8829 ' keyword arguments and pass the others over to the base ' | |
| 8830 'class, as\n' | |
| 8831 ' in:\n' | |
| 8832 '\n' | |
| 8833 ' class Philosopher:\n' | |
| 8834 ' def __init_subclass__(cls, /, default_name, ' | |
| 8835 '**kwargs):\n' | |
| 8836 ' super().__init_subclass__(**kwargs)\n' | |
| 8837 ' cls.default_name = default_name\n' | |
| 8838 '\n' | |
| 8839 ' class AustralianPhilosopher(Philosopher, ' | |
| 8840 'default_name="Bruce"):\n' | |
| 8841 ' pass\n' | |
| 8842 '\n' | |
| 8843 ' The default implementation "object.__init_subclass__" ' | |
| 8844 'does nothing,\n' | |
| 8845 ' but raises an error if it is called with any arguments.\n' | |
| 8846 '\n' | |
| 8847 ' Note: The metaclass hint "metaclass" is consumed by the ' | |
| 8848 'rest of\n' | |
| 8849 ' the type machinery, and is never passed to ' | |
| 8850 '"__init_subclass__"\n' | |
| 8851 ' implementations. The actual metaclass (rather than the ' | |
| 8852 'explicit\n' | |
| 8853 ' hint) can be accessed as "type(cls)".\n' | |
| 8854 '\n' | |
| 8855 ' New in version 3.6.\n' | |
| 8856 '\n' | |
| 8857 '\n' | |
| 8858 'Metaclasses\n' | |
| 8859 '-----------\n' | |
| 8860 '\n' | |
| 8861 'By default, classes are constructed using "type()". The ' | |
| 8862 'class body is\n' | |
| 8863 'executed in a new namespace and the class name is bound ' | |
| 8864 'locally to the\n' | |
| 8865 'result of "type(name, bases, namespace)".\n' | |
| 8866 '\n' | |
| 8867 'The class creation process can be customized by passing the\n' | |
| 8868 '"metaclass" keyword argument in the class definition line, ' | |
| 8869 'or by\n' | |
| 8870 'inheriting from an existing class that included such an ' | |
| 8871 'argument. In\n' | |
| 8872 'the following example, both "MyClass" and "MySubclass" are ' | |
| 8873 'instances\n' | |
| 8874 'of "Meta":\n' | |
| 8875 '\n' | |
| 8876 ' class Meta(type):\n' | |
| 8877 ' pass\n' | |
| 8878 '\n' | |
| 8879 ' class MyClass(metaclass=Meta):\n' | |
| 8880 ' pass\n' | |
| 8881 '\n' | |
| 8882 ' class MySubclass(MyClass):\n' | |
| 8883 ' pass\n' | |
| 8884 '\n' | |
| 8885 'Any other keyword arguments that are specified in the class ' | |
| 8886 'definition\n' | |
| 8887 'are passed through to all metaclass operations described ' | |
| 8888 'below.\n' | |
| 8889 '\n' | |
| 8890 'When a class definition is executed, the following steps ' | |
| 8891 'occur:\n' | |
| 8892 '\n' | |
| 8893 '* MRO entries are resolved;\n' | |
| 8894 '\n' | |
| 8895 '* the appropriate metaclass is determined;\n' | |
| 8896 '\n' | |
| 8897 '* the class namespace is prepared;\n' | |
| 8898 '\n' | |
| 8899 '* the class body is executed;\n' | |
| 8900 '\n' | |
| 8901 '* the class object is created.\n' | |
| 8902 '\n' | |
| 8903 '\n' | |
| 8904 'Resolving MRO entries\n' | |
| 8905 '---------------------\n' | |
| 8906 '\n' | |
| 8907 'If a base that appears in class definition is not an ' | |
| 8908 'instance of\n' | |
| 8909 '"type", then an "__mro_entries__" method is searched on it. ' | |
| 8910 'If found,\n' | |
| 8911 'it is called with the original bases tuple. This method must ' | |
| 8912 'return a\n' | |
| 8913 'tuple of classes that will be used instead of this base. The ' | |
| 8914 'tuple may\n' | |
| 8915 'be empty, in such case the original base is ignored.\n' | |
| 8916 '\n' | |
| 8917 'See also: **PEP 560** - Core support for typing module and ' | |
| 8918 'generic\n' | |
| 8919 ' types\n' | |
| 8920 '\n' | |
| 8921 '\n' | |
| 8922 'Determining the appropriate metaclass\n' | |
| 8923 '-------------------------------------\n' | |
| 8924 '\n' | |
| 8925 'The appropriate metaclass for a class definition is ' | |
| 8926 'determined as\n' | |
| 8927 'follows:\n' | |
| 8928 '\n' | |
| 8929 '* if no bases and no explicit metaclass are given, then ' | |
| 8930 '"type()" is\n' | |
| 8931 ' used;\n' | |
| 8932 '\n' | |
| 8933 '* if an explicit metaclass is given and it is *not* an ' | |
| 8934 'instance of\n' | |
| 8935 ' "type()", then it is used directly as the metaclass;\n' | |
| 8936 '\n' | |
| 8937 '* if an instance of "type()" is given as the explicit ' | |
| 8938 'metaclass, or\n' | |
| 8939 ' bases are defined, then the most derived metaclass is ' | |
| 8940 'used.\n' | |
| 8941 '\n' | |
| 8942 'The most derived metaclass is selected from the explicitly ' | |
| 8943 'specified\n' | |
| 8944 'metaclass (if any) and the metaclasses (i.e. "type(cls)") of ' | |
| 8945 'all\n' | |
| 8946 'specified base classes. The most derived metaclass is one ' | |
| 8947 'which is a\n' | |
| 8948 'subtype of *all* of these candidate metaclasses. If none of ' | |
| 8949 'the\n' | |
| 8950 'candidate metaclasses meets that criterion, then the class ' | |
| 8951 'definition\n' | |
| 8952 'will fail with "TypeError".\n' | |
| 8953 '\n' | |
| 8954 '\n' | |
| 8955 'Preparing the class namespace\n' | |
| 8956 '-----------------------------\n' | |
| 8957 '\n' | |
| 8958 'Once the appropriate metaclass has been identified, then the ' | |
| 8959 'class\n' | |
| 8960 'namespace is prepared. If the metaclass has a "__prepare__" ' | |
| 8961 'attribute,\n' | |
| 8962 'it is called as "namespace = metaclass.__prepare__(name, ' | |
| 8963 'bases,\n' | |
| 8964 '**kwds)" (where the additional keyword arguments, if any, ' | |
| 8965 'come from\n' | |
| 8966 'the class definition).\n' | |
| 8967 '\n' | |
| 8968 'If the metaclass has no "__prepare__" attribute, then the ' | |
| 8969 'class\n' | |
| 8970 'namespace is initialised as an empty ordered mapping.\n' | |
| 8971 '\n' | |
| 8972 'See also:\n' | |
| 8973 '\n' | |
| 8974 ' **PEP 3115** - Metaclasses in Python 3000\n' | |
| 8975 ' Introduced the "__prepare__" namespace hook\n' | |
| 8976 '\n' | |
| 8977 '\n' | |
| 8978 'Executing the class body\n' | |
| 8979 '------------------------\n' | |
| 8980 '\n' | |
| 8981 'The class body is executed (approximately) as "exec(body, ' | |
| 8982 'globals(),\n' | |
| 8983 'namespace)". The key difference from a normal call to ' | |
| 8984 '"exec()" is that\n' | |
| 8985 'lexical scoping allows the class body (including any ' | |
| 8986 'methods) to\n' | |
| 8987 'reference names from the current and outer scopes when the ' | |
| 8988 'class\n' | |
| 8989 'definition occurs inside a function.\n' | |
| 8990 '\n' | |
| 8991 'However, even when the class definition occurs inside the ' | |
| 8992 'function,\n' | |
| 8993 'methods defined inside the class still cannot see names ' | |
| 8994 'defined at the\n' | |
| 8995 'class scope. Class variables must be accessed through the ' | |
| 8996 'first\n' | |
| 8997 'parameter of instance or class methods, or through the ' | |
| 8998 'implicit\n' | |
| 8999 'lexically scoped "__class__" reference described in the next ' | |
| 9000 'section.\n' | |
| 9001 '\n' | |
| 9002 '\n' | |
| 9003 'Creating the class object\n' | |
| 9004 '-------------------------\n' | |
| 9005 '\n' | |
| 9006 'Once the class namespace has been populated by executing the ' | |
| 9007 'class\n' | |
| 9008 'body, the class object is created by calling ' | |
| 9009 '"metaclass(name, bases,\n' | |
| 9010 'namespace, **kwds)" (the additional keywords passed here are ' | |
| 9011 'the same\n' | |
| 9012 'as those passed to "__prepare__").\n' | |
| 9013 '\n' | |
| 9014 'This class object is the one that will be referenced by the ' | |
| 9015 'zero-\n' | |
| 9016 'argument form of "super()". "__class__" is an implicit ' | |
| 9017 'closure\n' | |
| 9018 'reference created by the compiler if any methods in a class ' | |
| 9019 'body refer\n' | |
| 9020 'to either "__class__" or "super". This allows the zero ' | |
| 9021 'argument form\n' | |
| 9022 'of "super()" to correctly identify the class being defined ' | |
| 9023 'based on\n' | |
| 9024 'lexical scoping, while the class or instance that was used ' | |
| 9025 'to make the\n' | |
| 9026 'current call is identified based on the first argument ' | |
| 9027 'passed to the\n' | |
| 9028 'method.\n' | |
| 9029 '\n' | |
| 9030 '**CPython implementation detail:** In CPython 3.6 and later, ' | |
| 9031 'the\n' | |
| 9032 '"__class__" cell is passed to the metaclass as a ' | |
| 9033 '"__classcell__" entry\n' | |
| 9034 'in the class namespace. If present, this must be propagated ' | |
| 9035 'up to the\n' | |
| 9036 '"type.__new__" call in order for the class to be ' | |
| 9037 'initialised\n' | |
| 9038 'correctly. Failing to do so will result in a "RuntimeError" ' | |
| 9039 'in Python\n' | |
| 9040 '3.8.\n' | |
| 9041 '\n' | |
| 9042 'When using the default metaclass "type", or any metaclass ' | |
| 9043 'that\n' | |
| 9044 'ultimately calls "type.__new__", the following additional\n' | |
| 9045 'customisation steps are invoked after creating the class ' | |
| 9046 'object:\n' | |
| 9047 '\n' | |
| 9048 '* first, "type.__new__" collects all of the descriptors in ' | |
| 9049 'the class\n' | |
| 9050 ' namespace that define a "__set_name__()" method;\n' | |
| 9051 '\n' | |
| 9052 '* second, all of these "__set_name__" methods are called ' | |
| 9053 'with the\n' | |
| 9054 ' class being defined and the assigned name of that ' | |
| 9055 'particular\n' | |
| 9056 ' descriptor;\n' | |
| 9057 '\n' | |
| 9058 '* finally, the "__init_subclass__()" hook is called on the ' | |
| 9059 'immediate\n' | |
| 9060 ' parent of the new class in its method resolution order.\n' | |
| 9061 '\n' | |
| 9062 'After the class object is created, it is passed to the ' | |
| 9063 'class\n' | |
| 9064 'decorators included in the class definition (if any) and the ' | |
| 9065 'resulting\n' | |
| 9066 'object is bound in the local namespace as the defined ' | |
| 9067 'class.\n' | |
| 9068 '\n' | |
| 9069 'When a new class is created by "type.__new__", the object ' | |
| 9070 'provided as\n' | |
| 9071 'the namespace parameter is copied to a new ordered mapping ' | |
| 9072 'and the\n' | |
| 9073 'original object is discarded. The new copy is wrapped in a ' | |
| 9074 'read-only\n' | |
| 9075 'proxy, which becomes the "__dict__" attribute of the class ' | |
| 9076 'object.\n' | |
| 9077 '\n' | |
| 9078 'See also:\n' | |
| 9079 '\n' | |
| 9080 ' **PEP 3135** - New super\n' | |
| 9081 ' Describes the implicit "__class__" closure reference\n' | |
| 9082 '\n' | |
| 9083 '\n' | |
| 9084 'Uses for metaclasses\n' | |
| 9085 '--------------------\n' | |
| 9086 '\n' | |
| 9087 'The potential uses for metaclasses are boundless. Some ideas ' | |
| 9088 'that have\n' | |
| 9089 'been explored include enum, logging, interface checking, ' | |
| 9090 'automatic\n' | |
| 9091 'delegation, automatic property creation, proxies, ' | |
| 9092 'frameworks, and\n' | |
| 9093 'automatic resource locking/synchronization.\n' | |
| 9094 '\n' | |
| 9095 '\n' | |
| 9096 'Customizing instance and subclass checks\n' | |
| 9097 '========================================\n' | |
| 9098 '\n' | |
| 9099 'The following methods are used to override the default ' | |
| 9100 'behavior of the\n' | |
| 9101 '"isinstance()" and "issubclass()" built-in functions.\n' | |
| 9102 '\n' | |
| 9103 'In particular, the metaclass "abc.ABCMeta" implements these ' | |
| 9104 'methods in\n' | |
| 9105 'order to allow the addition of Abstract Base Classes (ABCs) ' | |
| 9106 'as\n' | |
| 9107 '“virtual base classes” to any class or type (including ' | |
| 9108 'built-in\n' | |
| 9109 'types), including other ABCs.\n' | |
| 9110 '\n' | |
| 9111 'class.__instancecheck__(self, instance)\n' | |
| 9112 '\n' | |
| 9113 ' Return true if *instance* should be considered a (direct ' | |
| 9114 'or\n' | |
| 9115 ' indirect) instance of *class*. If defined, called to ' | |
| 9116 'implement\n' | |
| 9117 ' "isinstance(instance, class)".\n' | |
| 9118 '\n' | |
| 9119 'class.__subclasscheck__(self, subclass)\n' | |
| 9120 '\n' | |
| 9121 ' Return true if *subclass* should be considered a (direct ' | |
| 9122 'or\n' | |
| 9123 ' indirect) subclass of *class*. If defined, called to ' | |
| 9124 'implement\n' | |
| 9125 ' "issubclass(subclass, class)".\n' | |
| 9126 '\n' | |
| 9127 'Note that these methods are looked up on the type ' | |
| 9128 '(metaclass) of a\n' | |
| 9129 'class. They cannot be defined as class methods in the ' | |
| 9130 'actual class.\n' | |
| 9131 'This is consistent with the lookup of special methods that ' | |
| 9132 'are called\n' | |
| 9133 'on instances, only in this case the instance is itself a ' | |
| 9134 'class.\n' | |
| 9135 '\n' | |
| 9136 'See also:\n' | |
| 9137 '\n' | |
| 9138 ' **PEP 3119** - Introducing Abstract Base Classes\n' | |
| 9139 ' Includes the specification for customizing ' | |
| 9140 '"isinstance()" and\n' | |
| 9141 ' "issubclass()" behavior through "__instancecheck__()" ' | |
| 9142 'and\n' | |
| 9143 ' "__subclasscheck__()", with motivation for this ' | |
| 9144 'functionality in\n' | |
| 9145 ' the context of adding Abstract Base Classes (see the ' | |
| 9146 '"abc"\n' | |
| 9147 ' module) to the language.\n' | |
| 9148 '\n' | |
| 9149 '\n' | |
| 9150 'Emulating generic types\n' | |
| 9151 '=======================\n' | |
| 9152 '\n' | |
| 9153 'One can implement the generic class syntax as specified by ' | |
| 9154 '**PEP 484**\n' | |
| 9155 '(for example "List[int]") by defining a special method:\n' | |
| 9156 '\n' | |
| 9157 'classmethod object.__class_getitem__(cls, key)\n' | |
| 9158 '\n' | |
| 9159 ' Return an object representing the specialization of a ' | |
| 9160 'generic class\n' | |
| 9161 ' by type arguments found in *key*.\n' | |
| 9162 '\n' | |
| 9163 'This method is looked up on the class object itself, and ' | |
| 9164 'when defined\n' | |
| 9165 'in the class body, this method is implicitly a class ' | |
| 9166 'method. Note,\n' | |
| 9167 'this mechanism is primarily reserved for use with static ' | |
| 9168 'type hints,\n' | |
| 9169 'other usage is discouraged.\n' | |
| 9170 '\n' | |
| 9171 'See also: **PEP 560** - Core support for typing module and ' | |
| 9172 'generic\n' | |
| 9173 ' types\n' | |
| 9174 '\n' | |
| 9175 '\n' | |
| 9176 'Emulating callable objects\n' | |
| 9177 '==========================\n' | |
| 9178 '\n' | |
| 9179 'object.__call__(self[, args...])\n' | |
| 9180 '\n' | |
| 9181 ' Called when the instance is “called” as a function; if ' | |
| 9182 'this method\n' | |
| 9183 ' is defined, "x(arg1, arg2, ...)" is a shorthand for\n' | |
| 9184 ' "x.__call__(arg1, arg2, ...)".\n' | |
| 9185 '\n' | |
| 9186 '\n' | |
| 9187 'Emulating container types\n' | |
| 9188 '=========================\n' | |
| 9189 '\n' | |
| 9190 'The following methods can be defined to implement container ' | |
| 9191 'objects.\n' | |
| 9192 'Containers usually are sequences (such as lists or tuples) ' | |
| 9193 'or mappings\n' | |
| 9194 '(like dictionaries), but can represent other containers as ' | |
| 9195 'well. The\n' | |
| 9196 'first set of methods is used either to emulate a sequence or ' | |
| 9197 'to\n' | |
| 9198 'emulate a mapping; the difference is that for a sequence, ' | |
| 9199 'the\n' | |
| 9200 'allowable keys should be the integers *k* for which "0 <= k ' | |
| 9201 '< N" where\n' | |
| 9202 '*N* is the length of the sequence, or slice objects, which ' | |
| 9203 'define a\n' | |
| 9204 'range of items. It is also recommended that mappings ' | |
| 9205 'provide the\n' | |
| 9206 'methods "keys()", "values()", "items()", "get()", ' | |
| 9207 '"clear()",\n' | |
| 9208 '"setdefault()", "pop()", "popitem()", "copy()", and ' | |
| 9209 '"update()"\n' | |
| 9210 'behaving similar to those for Python’s standard dictionary ' | |
| 9211 'objects.\n' | |
| 9212 'The "collections.abc" module provides a "MutableMapping" ' | |
| 9213 'abstract base\n' | |
| 9214 'class to help create those methods from a base set of ' | |
| 9215 '"__getitem__()",\n' | |
| 9216 '"__setitem__()", "__delitem__()", and "keys()". Mutable ' | |
| 9217 'sequences\n' | |
| 9218 'should provide methods "append()", "count()", "index()", ' | |
| 9219 '"extend()",\n' | |
| 9220 '"insert()", "pop()", "remove()", "reverse()" and "sort()", ' | |
| 9221 'like Python\n' | |
| 9222 'standard list objects. Finally, sequence types should ' | |
| 9223 'implement\n' | |
| 9224 'addition (meaning concatenation) and multiplication ' | |
| 9225 '(meaning\n' | |
| 9226 'repetition) by defining the methods "__add__()", ' | |
| 9227 '"__radd__()",\n' | |
| 9228 '"__iadd__()", "__mul__()", "__rmul__()" and "__imul__()" ' | |
| 9229 'described\n' | |
| 9230 'below; they should not define other numerical operators. It ' | |
| 9231 'is\n' | |
| 9232 'recommended that both mappings and sequences implement the\n' | |
| 9233 '"__contains__()" method to allow efficient use of the "in" ' | |
| 9234 'operator;\n' | |
| 9235 'for mappings, "in" should search the mapping’s keys; for ' | |
| 9236 'sequences, it\n' | |
| 9237 'should search through the values. It is further recommended ' | |
| 9238 'that both\n' | |
| 9239 'mappings and sequences implement the "__iter__()" method to ' | |
| 9240 'allow\n' | |
| 9241 'efficient iteration through the container; for mappings, ' | |
| 9242 '"__iter__()"\n' | |
| 9243 'should iterate through the object’s keys; for sequences, it ' | |
| 9244 'should\n' | |
| 9245 'iterate through the values.\n' | |
| 9246 '\n' | |
| 9247 'object.__len__(self)\n' | |
| 9248 '\n' | |
| 9249 ' Called to implement the built-in function "len()". ' | |
| 9250 'Should return\n' | |
| 9251 ' the length of the object, an integer ">=" 0. Also, an ' | |
| 9252 'object that\n' | |
| 9253 ' doesn’t define a "__bool__()" method and whose ' | |
| 9254 '"__len__()" method\n' | |
| 9255 ' returns zero is considered to be false in a Boolean ' | |
| 9256 'context.\n' | |
| 9257 '\n' | |
| 9258 ' **CPython implementation detail:** In CPython, the length ' | |
| 9259 'is\n' | |
| 9260 ' required to be at most "sys.maxsize". If the length is ' | |
| 9261 'larger than\n' | |
| 9262 ' "sys.maxsize" some features (such as "len()") may raise\n' | |
| 9263 ' "OverflowError". To prevent raising "OverflowError" by ' | |
| 9264 'truth value\n' | |
| 9265 ' testing, an object must define a "__bool__()" method.\n' | |
| 9266 '\n' | |
| 9267 'object.__length_hint__(self)\n' | |
| 9268 '\n' | |
| 9269 ' Called to implement "operator.length_hint()". Should ' | |
| 9270 'return an\n' | |
| 9271 ' estimated length for the object (which may be greater or ' | |
| 9272 'less than\n' | |
| 9273 ' the actual length). The length must be an integer ">=" 0. ' | |
| 9274 'The\n' | |
| 9275 ' return value may also be "NotImplemented", which is ' | |
| 9276 'treated the\n' | |
| 9277 ' same as if the "__length_hint__" method didn’t exist at ' | |
| 9278 'all. This\n' | |
| 9279 ' method is purely an optimization and is never required ' | |
| 9280 'for\n' | |
| 9281 ' correctness.\n' | |
| 9282 '\n' | |
| 9283 ' New in version 3.4.\n' | |
| 9284 '\n' | |
| 9285 'Note: Slicing is done exclusively with the following three ' | |
| 9286 'methods.\n' | |
| 9287 ' A call like\n' | |
| 9288 '\n' | |
| 9289 ' a[1:2] = b\n' | |
| 9290 '\n' | |
| 9291 ' is translated to\n' | |
| 9292 '\n' | |
| 9293 ' a[slice(1, 2, None)] = b\n' | |
| 9294 '\n' | |
| 9295 ' and so forth. Missing slice items are always filled in ' | |
| 9296 'with "None".\n' | |
| 9297 '\n' | |
| 9298 'object.__getitem__(self, key)\n' | |
| 9299 '\n' | |
| 9300 ' Called to implement evaluation of "self[key]". For ' | |
| 9301 'sequence types,\n' | |
| 9302 ' the accepted keys should be integers and slice objects. ' | |
| 9303 'Note that\n' | |
| 9304 ' the special interpretation of negative indexes (if the ' | |
| 9305 'class wishes\n' | |
| 9306 ' to emulate a sequence type) is up to the "__getitem__()" ' | |
| 9307 'method. If\n' | |
| 9308 ' *key* is of an inappropriate type, "TypeError" may be ' | |
| 9309 'raised; if of\n' | |
| 9310 ' a value outside the set of indexes for the sequence ' | |
| 9311 '(after any\n' | |
| 9312 ' special interpretation of negative values), "IndexError" ' | |
| 9313 'should be\n' | |
| 9314 ' raised. For mapping types, if *key* is missing (not in ' | |
| 9315 'the\n' | |
| 9316 ' container), "KeyError" should be raised.\n' | |
| 9317 '\n' | |
| 9318 ' Note: "for" loops expect that an "IndexError" will be ' | |
| 9319 'raised for\n' | |
| 9320 ' illegal indexes to allow proper detection of the end of ' | |
| 9321 'the\n' | |
| 9322 ' sequence.\n' | |
| 9323 '\n' | |
| 9324 'object.__setitem__(self, key, value)\n' | |
| 9325 '\n' | |
| 9326 ' Called to implement assignment to "self[key]". Same note ' | |
| 9327 'as for\n' | |
| 9328 ' "__getitem__()". This should only be implemented for ' | |
| 9329 'mappings if\n' | |
| 9330 ' the objects support changes to the values for keys, or if ' | |
| 9331 'new keys\n' | |
| 9332 ' can be added, or for sequences if elements can be ' | |
| 9333 'replaced. The\n' | |
| 9334 ' same exceptions should be raised for improper *key* ' | |
| 9335 'values as for\n' | |
| 9336 ' the "__getitem__()" method.\n' | |
| 9337 '\n' | |
| 9338 'object.__delitem__(self, key)\n' | |
| 9339 '\n' | |
| 9340 ' Called to implement deletion of "self[key]". Same note ' | |
| 9341 'as for\n' | |
| 9342 ' "__getitem__()". This should only be implemented for ' | |
| 9343 'mappings if\n' | |
| 9344 ' the objects support removal of keys, or for sequences if ' | |
| 9345 'elements\n' | |
| 9346 ' can be removed from the sequence. The same exceptions ' | |
| 9347 'should be\n' | |
| 9348 ' raised for improper *key* values as for the ' | |
| 9349 '"__getitem__()" method.\n' | |
| 9350 '\n' | |
| 9351 'object.__missing__(self, key)\n' | |
| 9352 '\n' | |
| 9353 ' Called by "dict"."__getitem__()" to implement "self[key]" ' | |
| 9354 'for dict\n' | |
| 9355 ' subclasses when key is not in the dictionary.\n' | |
| 9356 '\n' | |
| 9357 'object.__iter__(self)\n' | |
| 9358 '\n' | |
| 9359 ' This method is called when an iterator is required for a ' | |
| 9360 'container.\n' | |
| 9361 ' This method should return a new iterator object that can ' | |
| 9362 'iterate\n' | |
| 9363 ' over all the objects in the container. For mappings, it ' | |
| 9364 'should\n' | |
| 9365 ' iterate over the keys of the container.\n' | |
| 9366 '\n' | |
| 9367 ' Iterator objects also need to implement this method; they ' | |
| 9368 'are\n' | |
| 9369 ' required to return themselves. For more information on ' | |
| 9370 'iterator\n' | |
| 9371 ' objects, see Iterator Types.\n' | |
| 9372 '\n' | |
| 9373 'object.__reversed__(self)\n' | |
| 9374 '\n' | |
| 9375 ' Called (if present) by the "reversed()" built-in to ' | |
| 9376 'implement\n' | |
| 9377 ' reverse iteration. It should return a new iterator ' | |
| 9378 'object that\n' | |
| 9379 ' iterates over all the objects in the container in reverse ' | |
| 9380 'order.\n' | |
| 9381 '\n' | |
| 9382 ' If the "__reversed__()" method is not provided, the ' | |
| 9383 '"reversed()"\n' | |
| 9384 ' built-in will fall back to using the sequence protocol ' | |
| 9385 '("__len__()"\n' | |
| 9386 ' and "__getitem__()"). Objects that support the sequence ' | |
| 9387 'protocol\n' | |
| 9388 ' should only provide "__reversed__()" if they can provide ' | |
| 9389 'an\n' | |
| 9390 ' implementation that is more efficient than the one ' | |
| 9391 'provided by\n' | |
| 9392 ' "reversed()".\n' | |
| 9393 '\n' | |
| 9394 'The membership test operators ("in" and "not in") are ' | |
| 9395 'normally\n' | |
| 9396 'implemented as an iteration through a container. However, ' | |
| 9397 'container\n' | |
| 9398 'objects can supply the following special method with a more ' | |
| 9399 'efficient\n' | |
| 9400 'implementation, which also does not require the object be ' | |
| 9401 'iterable.\n' | |
| 9402 '\n' | |
| 9403 'object.__contains__(self, item)\n' | |
| 9404 '\n' | |
| 9405 ' Called to implement membership test operators. Should ' | |
| 9406 'return true\n' | |
| 9407 ' if *item* is in *self*, false otherwise. For mapping ' | |
| 9408 'objects, this\n' | |
| 9409 ' should consider the keys of the mapping rather than the ' | |
| 9410 'values or\n' | |
| 9411 ' the key-item pairs.\n' | |
| 9412 '\n' | |
| 9413 ' For objects that don’t define "__contains__()", the ' | |
| 9414 'membership test\n' | |
| 9415 ' first tries iteration via "__iter__()", then the old ' | |
| 9416 'sequence\n' | |
| 9417 ' iteration protocol via "__getitem__()", see this section ' | |
| 9418 'in the\n' | |
| 9419 ' language reference.\n' | |
| 9420 '\n' | |
| 9421 '\n' | |
| 9422 'Emulating numeric types\n' | |
| 9423 '=======================\n' | |
| 9424 '\n' | |
| 9425 'The following methods can be defined to emulate numeric ' | |
| 9426 'objects.\n' | |
| 9427 'Methods corresponding to operations that are not supported ' | |
| 9428 'by the\n' | |
| 9429 'particular kind of number implemented (e.g., bitwise ' | |
| 9430 'operations for\n' | |
| 9431 'non-integral numbers) should be left undefined.\n' | |
| 9432 '\n' | |
| 9433 'object.__add__(self, other)\n' | |
| 9434 'object.__sub__(self, other)\n' | |
| 9435 'object.__mul__(self, other)\n' | |
| 9436 'object.__matmul__(self, other)\n' | |
| 9437 'object.__truediv__(self, other)\n' | |
| 9438 'object.__floordiv__(self, other)\n' | |
| 9439 'object.__mod__(self, other)\n' | |
| 9440 'object.__divmod__(self, other)\n' | |
| 9441 'object.__pow__(self, other[, modulo])\n' | |
| 9442 'object.__lshift__(self, other)\n' | |
| 9443 'object.__rshift__(self, other)\n' | |
| 9444 'object.__and__(self, other)\n' | |
| 9445 'object.__xor__(self, other)\n' | |
| 9446 'object.__or__(self, other)\n' | |
| 9447 '\n' | |
| 9448 ' These methods are called to implement the binary ' | |
| 9449 'arithmetic\n' | |
| 9450 ' operations ("+", "-", "*", "@", "/", "//", "%", ' | |
| 9451 '"divmod()",\n' | |
| 9452 ' "pow()", "**", "<<", ">>", "&", "^", "|"). For instance, ' | |
| 9453 'to\n' | |
| 9454 ' evaluate the expression "x + y", where *x* is an instance ' | |
| 9455 'of a\n' | |
| 9456 ' class that has an "__add__()" method, "x.__add__(y)" is ' | |
| 9457 'called.\n' | |
| 9458 ' The "__divmod__()" method should be the equivalent to ' | |
| 9459 'using\n' | |
| 9460 ' "__floordiv__()" and "__mod__()"; it should not be ' | |
| 9461 'related to\n' | |
| 9462 ' "__truediv__()". Note that "__pow__()" should be defined ' | |
| 9463 'to accept\n' | |
| 9464 ' an optional third argument if the ternary version of the ' | |
| 9465 'built-in\n' | |
| 9466 ' "pow()" function is to be supported.\n' | |
| 9467 '\n' | |
| 9468 ' If one of those methods does not support the operation ' | |
| 9469 'with the\n' | |
| 9470 ' supplied arguments, it should return "NotImplemented".\n' | |
| 9471 '\n' | |
| 9472 'object.__radd__(self, other)\n' | |
| 9473 'object.__rsub__(self, other)\n' | |
| 9474 'object.__rmul__(self, other)\n' | |
| 9475 'object.__rmatmul__(self, other)\n' | |
| 9476 'object.__rtruediv__(self, other)\n' | |
| 9477 'object.__rfloordiv__(self, other)\n' | |
| 9478 'object.__rmod__(self, other)\n' | |
| 9479 'object.__rdivmod__(self, other)\n' | |
| 9480 'object.__rpow__(self, other)\n' | |
| 9481 'object.__rlshift__(self, other)\n' | |
| 9482 'object.__rrshift__(self, other)\n' | |
| 9483 'object.__rand__(self, other)\n' | |
| 9484 'object.__rxor__(self, other)\n' | |
| 9485 'object.__ror__(self, other)\n' | |
| 9486 '\n' | |
| 9487 ' These methods are called to implement the binary ' | |
| 9488 'arithmetic\n' | |
| 9489 ' operations ("+", "-", "*", "@", "/", "//", "%", ' | |
| 9490 '"divmod()",\n' | |
| 9491 ' "pow()", "**", "<<", ">>", "&", "^", "|") with reflected ' | |
| 9492 '(swapped)\n' | |
| 9493 ' operands. These functions are only called if the left ' | |
| 9494 'operand does\n' | |
| 9495 ' not support the corresponding operation [3] and the ' | |
| 9496 'operands are of\n' | |
| 9497 ' different types. [4] For instance, to evaluate the ' | |
| 9498 'expression "x -\n' | |
| 9499 ' y", where *y* is an instance of a class that has an ' | |
| 9500 '"__rsub__()"\n' | |
| 9501 ' method, "y.__rsub__(x)" is called if "x.__sub__(y)" ' | |
| 9502 'returns\n' | |
| 9503 ' *NotImplemented*.\n' | |
| 9504 '\n' | |
| 9505 ' Note that ternary "pow()" will not try calling ' | |
| 9506 '"__rpow__()" (the\n' | |
| 9507 ' coercion rules would become too complicated).\n' | |
| 9508 '\n' | |
| 9509 ' Note: If the right operand’s type is a subclass of the ' | |
| 9510 'left\n' | |
| 9511 ' operand’s type and that subclass provides the reflected ' | |
| 9512 'method\n' | |
| 9513 ' for the operation, this method will be called before ' | |
| 9514 'the left\n' | |
| 9515 ' operand’s non-reflected method. This behavior allows ' | |
| 9516 'subclasses\n' | |
| 9517 ' to override their ancestors’ operations.\n' | |
| 9518 '\n' | |
| 9519 'object.__iadd__(self, other)\n' | |
| 9520 'object.__isub__(self, other)\n' | |
| 9521 'object.__imul__(self, other)\n' | |
| 9522 'object.__imatmul__(self, other)\n' | |
| 9523 'object.__itruediv__(self, other)\n' | |
| 9524 'object.__ifloordiv__(self, other)\n' | |
| 9525 'object.__imod__(self, other)\n' | |
| 9526 'object.__ipow__(self, other[, modulo])\n' | |
| 9527 'object.__ilshift__(self, other)\n' | |
| 9528 'object.__irshift__(self, other)\n' | |
| 9529 'object.__iand__(self, other)\n' | |
| 9530 'object.__ixor__(self, other)\n' | |
| 9531 'object.__ior__(self, other)\n' | |
| 9532 '\n' | |
| 9533 ' These methods are called to implement the augmented ' | |
| 9534 'arithmetic\n' | |
| 9535 ' assignments ("+=", "-=", "*=", "@=", "/=", "//=", "%=", ' | |
| 9536 '"**=",\n' | |
| 9537 ' "<<=", ">>=", "&=", "^=", "|="). These methods should ' | |
| 9538 'attempt to\n' | |
| 9539 ' do the operation in-place (modifying *self*) and return ' | |
| 9540 'the result\n' | |
| 9541 ' (which could be, but does not have to be, *self*). If a ' | |
| 9542 'specific\n' | |
| 9543 ' method is not defined, the augmented assignment falls ' | |
| 9544 'back to the\n' | |
| 9545 ' normal methods. For instance, if *x* is an instance of a ' | |
| 9546 'class\n' | |
| 9547 ' with an "__iadd__()" method, "x += y" is equivalent to "x ' | |
| 9548 '=\n' | |
| 9549 ' x.__iadd__(y)" . Otherwise, "x.__add__(y)" and ' | |
| 9550 '"y.__radd__(x)" are\n' | |
| 9551 ' considered, as with the evaluation of "x + y". In ' | |
| 9552 'certain\n' | |
| 9553 ' situations, augmented assignment can result in unexpected ' | |
| 9554 'errors\n' | |
| 9555 ' (see Why does a_tuple[i] += [‘item’] raise an exception ' | |
| 9556 'when the\n' | |
| 9557 ' addition works?), but this behavior is in fact part of ' | |
| 9558 'the data\n' | |
| 9559 ' model.\n' | |
| 9560 '\n' | |
| 9561 'object.__neg__(self)\n' | |
| 9562 'object.__pos__(self)\n' | |
| 9563 'object.__abs__(self)\n' | |
| 9564 'object.__invert__(self)\n' | |
| 9565 '\n' | |
| 9566 ' Called to implement the unary arithmetic operations ("-", ' | |
| 9567 '"+",\n' | |
| 9568 ' "abs()" and "~").\n' | |
| 9569 '\n' | |
| 9570 'object.__complex__(self)\n' | |
| 9571 'object.__int__(self)\n' | |
| 9572 'object.__float__(self)\n' | |
| 9573 '\n' | |
| 9574 ' Called to implement the built-in functions "complex()", ' | |
| 9575 '"int()" and\n' | |
| 9576 ' "float()". Should return a value of the appropriate ' | |
| 9577 'type.\n' | |
| 9578 '\n' | |
| 9579 'object.__index__(self)\n' | |
| 9580 '\n' | |
| 9581 ' Called to implement "operator.index()", and whenever ' | |
| 9582 'Python needs\n' | |
| 9583 ' to losslessly convert the numeric object to an integer ' | |
| 9584 'object (such\n' | |
| 9585 ' as in slicing, or in the built-in "bin()", "hex()" and ' | |
| 9586 '"oct()"\n' | |
| 9587 ' functions). Presence of this method indicates that the ' | |
| 9588 'numeric\n' | |
| 9589 ' object is an integer type. Must return an integer.\n' | |
| 9590 '\n' | |
| 9591 ' If "__int__()", "__float__()" and "__complex__()" are not ' | |
| 9592 'defined\n' | |
| 9593 ' then corresponding built-in functions "int()", "float()" ' | |
| 9594 'and\n' | |
| 9595 ' "complex()" fall back to "__index__()".\n' | |
| 9596 '\n' | |
| 9597 'object.__round__(self[, ndigits])\n' | |
| 9598 'object.__trunc__(self)\n' | |
| 9599 'object.__floor__(self)\n' | |
| 9600 'object.__ceil__(self)\n' | |
| 9601 '\n' | |
| 9602 ' Called to implement the built-in function "round()" and ' | |
| 9603 '"math"\n' | |
| 9604 ' functions "trunc()", "floor()" and "ceil()". Unless ' | |
| 9605 '*ndigits* is\n' | |
| 9606 ' passed to "__round__()" all these methods should return ' | |
| 9607 'the value\n' | |
| 9608 ' of the object truncated to an "Integral" (typically an ' | |
| 9609 '"int").\n' | |
| 9610 '\n' | |
| 9611 ' If "__int__()" is not defined then the built-in function ' | |
| 9612 '"int()"\n' | |
| 9613 ' falls back to "__trunc__()".\n' | |
| 9614 '\n' | |
| 9615 '\n' | |
| 9616 'With Statement Context Managers\n' | |
| 9617 '===============================\n' | |
| 9618 '\n' | |
| 9619 'A *context manager* is an object that defines the runtime ' | |
| 9620 'context to\n' | |
| 9621 'be established when executing a "with" statement. The ' | |
| 9622 'context manager\n' | |
| 9623 'handles the entry into, and the exit from, the desired ' | |
| 9624 'runtime context\n' | |
| 9625 'for the execution of the block of code. Context managers ' | |
| 9626 'are normally\n' | |
| 9627 'invoked using the "with" statement (described in section The ' | |
| 9628 'with\n' | |
| 9629 'statement), but can also be used by directly invoking their ' | |
| 9630 'methods.\n' | |
| 9631 '\n' | |
| 9632 'Typical uses of context managers include saving and ' | |
| 9633 'restoring various\n' | |
| 9634 'kinds of global state, locking and unlocking resources, ' | |
| 9635 'closing opened\n' | |
| 9636 'files, etc.\n' | |
| 9637 '\n' | |
| 9638 'For more information on context managers, see Context ' | |
| 9639 'Manager Types.\n' | |
| 9640 '\n' | |
| 9641 'object.__enter__(self)\n' | |
| 9642 '\n' | |
| 9643 ' Enter the runtime context related to this object. The ' | |
| 9644 '"with"\n' | |
| 9645 ' statement will bind this method’s return value to the ' | |
| 9646 'target(s)\n' | |
| 9647 ' specified in the "as" clause of the statement, if any.\n' | |
| 9648 '\n' | |
| 9649 'object.__exit__(self, exc_type, exc_value, traceback)\n' | |
| 9650 '\n' | |
| 9651 ' Exit the runtime context related to this object. The ' | |
| 9652 'parameters\n' | |
| 9653 ' describe the exception that caused the context to be ' | |
| 9654 'exited. If the\n' | |
| 9655 ' context was exited without an exception, all three ' | |
| 9656 'arguments will\n' | |
| 9657 ' be "None".\n' | |
| 9658 '\n' | |
| 9659 ' If an exception is supplied, and the method wishes to ' | |
| 9660 'suppress the\n' | |
| 9661 ' exception (i.e., prevent it from being propagated), it ' | |
| 9662 'should\n' | |
| 9663 ' return a true value. Otherwise, the exception will be ' | |
| 9664 'processed\n' | |
| 9665 ' normally upon exit from this method.\n' | |
| 9666 '\n' | |
| 9667 ' Note that "__exit__()" methods should not reraise the ' | |
| 9668 'passed-in\n' | |
| 9669 ' exception; this is the caller’s responsibility.\n' | |
| 9670 '\n' | |
| 9671 'See also:\n' | |
| 9672 '\n' | |
| 9673 ' **PEP 343** - The “with” statement\n' | |
| 9674 ' The specification, background, and examples for the ' | |
| 9675 'Python "with"\n' | |
| 9676 ' statement.\n' | |
| 9677 '\n' | |
| 9678 '\n' | |
| 9679 'Special method lookup\n' | |
| 9680 '=====================\n' | |
| 9681 '\n' | |
| 9682 'For custom classes, implicit invocations of special methods ' | |
| 9683 'are only\n' | |
| 9684 'guaranteed to work correctly if defined on an object’s type, ' | |
| 9685 'not in\n' | |
| 9686 'the object’s instance dictionary. That behaviour is the ' | |
| 9687 'reason why\n' | |
| 9688 'the following code raises an exception:\n' | |
| 9689 '\n' | |
| 9690 ' >>> class C:\n' | |
| 9691 ' ... pass\n' | |
| 9692 ' ...\n' | |
| 9693 ' >>> c = C()\n' | |
| 9694 ' >>> c.__len__ = lambda: 5\n' | |
| 9695 ' >>> len(c)\n' | |
| 9696 ' Traceback (most recent call last):\n' | |
| 9697 ' File "<stdin>", line 1, in <module>\n' | |
| 9698 " TypeError: object of type 'C' has no len()\n" | |
| 9699 '\n' | |
| 9700 'The rationale behind this behaviour lies with a number of ' | |
| 9701 'special\n' | |
| 9702 'methods such as "__hash__()" and "__repr__()" that are ' | |
| 9703 'implemented by\n' | |
| 9704 'all objects, including type objects. If the implicit lookup ' | |
| 9705 'of these\n' | |
| 9706 'methods used the conventional lookup process, they would ' | |
| 9707 'fail when\n' | |
| 9708 'invoked on the type object itself:\n' | |
| 9709 '\n' | |
| 9710 ' >>> 1 .__hash__() == hash(1)\n' | |
| 9711 ' True\n' | |
| 9712 ' >>> int.__hash__() == hash(int)\n' | |
| 9713 ' Traceback (most recent call last):\n' | |
| 9714 ' File "<stdin>", line 1, in <module>\n' | |
| 9715 " TypeError: descriptor '__hash__' of 'int' object needs an " | |
| 9716 'argument\n' | |
| 9717 '\n' | |
| 9718 'Incorrectly attempting to invoke an unbound method of a ' | |
| 9719 'class in this\n' | |
| 9720 'way is sometimes referred to as ‘metaclass confusion’, and ' | |
| 9721 'is avoided\n' | |
| 9722 'by bypassing the instance when looking up special methods:\n' | |
| 9723 '\n' | |
| 9724 ' >>> type(1).__hash__(1) == hash(1)\n' | |
| 9725 ' True\n' | |
| 9726 ' >>> type(int).__hash__(int) == hash(int)\n' | |
| 9727 ' True\n' | |
| 9728 '\n' | |
| 9729 'In addition to bypassing any instance attributes in the ' | |
| 9730 'interest of\n' | |
| 9731 'correctness, implicit special method lookup generally also ' | |
| 9732 'bypasses\n' | |
| 9733 'the "__getattribute__()" method even of the object’s ' | |
| 9734 'metaclass:\n' | |
| 9735 '\n' | |
| 9736 ' >>> class Meta(type):\n' | |
| 9737 ' ... def __getattribute__(*args):\n' | |
| 9738 ' ... print("Metaclass getattribute invoked")\n' | |
| 9739 ' ... return type.__getattribute__(*args)\n' | |
| 9740 ' ...\n' | |
| 9741 ' >>> class C(object, metaclass=Meta):\n' | |
| 9742 ' ... def __len__(self):\n' | |
| 9743 ' ... return 10\n' | |
| 9744 ' ... def __getattribute__(*args):\n' | |
| 9745 ' ... print("Class getattribute invoked")\n' | |
| 9746 ' ... return object.__getattribute__(*args)\n' | |
| 9747 ' ...\n' | |
| 9748 ' >>> c = C()\n' | |
| 9749 ' >>> c.__len__() # Explicit lookup via ' | |
| 9750 'instance\n' | |
| 9751 ' Class getattribute invoked\n' | |
| 9752 ' 10\n' | |
| 9753 ' >>> type(c).__len__(c) # Explicit lookup via ' | |
| 9754 'type\n' | |
| 9755 ' Metaclass getattribute invoked\n' | |
| 9756 ' 10\n' | |
| 9757 ' >>> len(c) # Implicit lookup\n' | |
| 9758 ' 10\n' | |
| 9759 '\n' | |
| 9760 'Bypassing the "__getattribute__()" machinery in this fashion ' | |
| 9761 'provides\n' | |
| 9762 'significant scope for speed optimisations within the ' | |
| 9763 'interpreter, at\n' | |
| 9764 'the cost of some flexibility in the handling of special ' | |
| 9765 'methods (the\n' | |
| 9766 'special method *must* be set on the class object itself in ' | |
| 9767 'order to be\n' | |
| 9768 'consistently invoked by the interpreter).\n', | |
| 9769 'string-methods': 'String Methods\n' | |
| 9770 '**************\n' | |
| 9771 '\n' | |
| 9772 'Strings implement all of the common sequence operations, ' | |
| 9773 'along with\n' | |
| 9774 'the additional methods described below.\n' | |
| 9775 '\n' | |
| 9776 'Strings also support two styles of string formatting, one ' | |
| 9777 'providing a\n' | |
| 9778 'large degree of flexibility and customization (see ' | |
| 9779 '"str.format()",\n' | |
| 9780 'Format String Syntax and Custom String Formatting) and the ' | |
| 9781 'other based\n' | |
| 9782 'on C "printf" style formatting that handles a narrower ' | |
| 9783 'range of types\n' | |
| 9784 'and is slightly harder to use correctly, but is often ' | |
| 9785 'faster for the\n' | |
| 9786 'cases it can handle (printf-style String Formatting).\n' | |
| 9787 '\n' | |
| 9788 'The Text Processing Services section of the standard ' | |
| 9789 'library covers a\n' | |
| 9790 'number of other modules that provide various text related ' | |
| 9791 'utilities\n' | |
| 9792 '(including regular expression support in the "re" ' | |
| 9793 'module).\n' | |
| 9794 '\n' | |
| 9795 'str.capitalize()\n' | |
| 9796 '\n' | |
| 9797 ' Return a copy of the string with its first character ' | |
| 9798 'capitalized\n' | |
| 9799 ' and the rest lowercased.\n' | |
| 9800 '\n' | |
| 9801 ' Changed in version 3.8: The first character is now put ' | |
| 9802 'into\n' | |
| 9803 ' titlecase rather than uppercase. This means that ' | |
| 9804 'characters like\n' | |
| 9805 ' digraphs will only have their first letter capitalized, ' | |
| 9806 'instead of\n' | |
| 9807 ' the full character.\n' | |
| 9808 '\n' | |
| 9809 'str.casefold()\n' | |
| 9810 '\n' | |
| 9811 ' Return a casefolded copy of the string. Casefolded ' | |
| 9812 'strings may be\n' | |
| 9813 ' used for caseless matching.\n' | |
| 9814 '\n' | |
| 9815 ' Casefolding is similar to lowercasing but more ' | |
| 9816 'aggressive because\n' | |
| 9817 ' it is intended to remove all case distinctions in a ' | |
| 9818 'string. For\n' | |
| 9819 ' example, the German lowercase letter "\'ß\'" is ' | |
| 9820 'equivalent to ""ss"".\n' | |
| 9821 ' Since it is already lowercase, "lower()" would do ' | |
| 9822 'nothing to "\'ß\'";\n' | |
| 9823 ' "casefold()" converts it to ""ss"".\n' | |
| 9824 '\n' | |
| 9825 ' The casefolding algorithm is described in section 3.13 ' | |
| 9826 'of the\n' | |
| 9827 ' Unicode Standard.\n' | |
| 9828 '\n' | |
| 9829 ' New in version 3.3.\n' | |
| 9830 '\n' | |
| 9831 'str.center(width[, fillchar])\n' | |
| 9832 '\n' | |
| 9833 ' Return centered in a string of length *width*. Padding ' | |
| 9834 'is done\n' | |
| 9835 ' using the specified *fillchar* (default is an ASCII ' | |
| 9836 'space). The\n' | |
| 9837 ' original string is returned if *width* is less than or ' | |
| 9838 'equal to\n' | |
| 9839 ' "len(s)".\n' | |
| 9840 '\n' | |
| 9841 'str.count(sub[, start[, end]])\n' | |
| 9842 '\n' | |
| 9843 ' Return the number of non-overlapping occurrences of ' | |
| 9844 'substring *sub*\n' | |
| 9845 ' in the range [*start*, *end*]. Optional arguments ' | |
| 9846 '*start* and\n' | |
| 9847 ' *end* are interpreted as in slice notation.\n' | |
| 9848 '\n' | |
| 9849 'str.encode(encoding="utf-8", errors="strict")\n' | |
| 9850 '\n' | |
| 9851 ' Return an encoded version of the string as a bytes ' | |
| 9852 'object. Default\n' | |
| 9853 ' encoding is "\'utf-8\'". *errors* may be given to set a ' | |
| 9854 'different\n' | |
| 9855 ' error handling scheme. The default for *errors* is ' | |
| 9856 '"\'strict\'",\n' | |
| 9857 ' meaning that encoding errors raise a "UnicodeError". ' | |
| 9858 'Other possible\n' | |
| 9859 ' values are "\'ignore\'", "\'replace\'", ' | |
| 9860 '"\'xmlcharrefreplace\'",\n' | |
| 9861 ' "\'backslashreplace\'" and any other name registered ' | |
| 9862 'via\n' | |
| 9863 ' "codecs.register_error()", see section Error Handlers. ' | |
| 9864 'For a list\n' | |
| 9865 ' of possible encodings, see section Standard Encodings.\n' | |
| 9866 '\n' | |
| 9867 ' Changed in version 3.1: Support for keyword arguments ' | |
| 9868 'added.\n' | |
| 9869 '\n' | |
| 9870 'str.endswith(suffix[, start[, end]])\n' | |
| 9871 '\n' | |
| 9872 ' Return "True" if the string ends with the specified ' | |
| 9873 '*suffix*,\n' | |
| 9874 ' otherwise return "False". *suffix* can also be a tuple ' | |
| 9875 'of suffixes\n' | |
| 9876 ' to look for. With optional *start*, test beginning at ' | |
| 9877 'that\n' | |
| 9878 ' position. With optional *end*, stop comparing at that ' | |
| 9879 'position.\n' | |
| 9880 '\n' | |
| 9881 'str.expandtabs(tabsize=8)\n' | |
| 9882 '\n' | |
| 9883 ' Return a copy of the string where all tab characters ' | |
| 9884 'are replaced\n' | |
| 9885 ' by one or more spaces, depending on the current column ' | |
| 9886 'and the\n' | |
| 9887 ' given tab size. Tab positions occur every *tabsize* ' | |
| 9888 'characters\n' | |
| 9889 ' (default is 8, giving tab positions at columns 0, 8, 16 ' | |
| 9890 'and so on).\n' | |
| 9891 ' To expand the string, the current column is set to zero ' | |
| 9892 'and the\n' | |
| 9893 ' string is examined character by character. If the ' | |
| 9894 'character is a\n' | |
| 9895 ' tab ("\\t"), one or more space characters are inserted ' | |
| 9896 'in the result\n' | |
| 9897 ' until the current column is equal to the next tab ' | |
| 9898 'position. (The\n' | |
| 9899 ' tab character itself is not copied.) If the character ' | |
| 9900 'is a newline\n' | |
| 9901 ' ("\\n") or return ("\\r"), it is copied and the current ' | |
| 9902 'column is\n' | |
| 9903 ' reset to zero. Any other character is copied unchanged ' | |
| 9904 'and the\n' | |
| 9905 ' current column is incremented by one regardless of how ' | |
| 9906 'the\n' | |
| 9907 ' character is represented when printed.\n' | |
| 9908 '\n' | |
| 9909 " >>> '01\\t012\\t0123\\t01234'.expandtabs()\n" | |
| 9910 " '01 012 0123 01234'\n" | |
| 9911 " >>> '01\\t012\\t0123\\t01234'.expandtabs(4)\n" | |
| 9912 " '01 012 0123 01234'\n" | |
| 9913 '\n' | |
| 9914 'str.find(sub[, start[, end]])\n' | |
| 9915 '\n' | |
| 9916 ' Return the lowest index in the string where substring ' | |
| 9917 '*sub* is\n' | |
| 9918 ' found within the slice "s[start:end]". Optional ' | |
| 9919 'arguments *start*\n' | |
| 9920 ' and *end* are interpreted as in slice notation. Return ' | |
| 9921 '"-1" if\n' | |
| 9922 ' *sub* is not found.\n' | |
| 9923 '\n' | |
| 9924 ' Note: The "find()" method should be used only if you ' | |
| 9925 'need to know\n' | |
| 9926 ' the position of *sub*. To check if *sub* is a ' | |
| 9927 'substring or not,\n' | |
| 9928 ' use the "in" operator:\n' | |
| 9929 '\n' | |
| 9930 " >>> 'Py' in 'Python'\n" | |
| 9931 ' True\n' | |
| 9932 '\n' | |
| 9933 'str.format(*args, **kwargs)\n' | |
| 9934 '\n' | |
| 9935 ' Perform a string formatting operation. The string on ' | |
| 9936 'which this\n' | |
| 9937 ' method is called can contain literal text or ' | |
| 9938 'replacement fields\n' | |
| 9939 ' delimited by braces "{}". Each replacement field ' | |
| 9940 'contains either\n' | |
| 9941 ' the numeric index of a positional argument, or the name ' | |
| 9942 'of a\n' | |
| 9943 ' keyword argument. Returns a copy of the string where ' | |
| 9944 'each\n' | |
| 9945 ' replacement field is replaced with the string value of ' | |
| 9946 'the\n' | |
| 9947 ' corresponding argument.\n' | |
| 9948 '\n' | |
| 9949 ' >>> "The sum of 1 + 2 is {0}".format(1+2)\n' | |
| 9950 " 'The sum of 1 + 2 is 3'\n" | |
| 9951 '\n' | |
| 9952 ' See Format String Syntax for a description of the ' | |
| 9953 'various\n' | |
| 9954 ' formatting options that can be specified in format ' | |
| 9955 'strings.\n' | |
| 9956 '\n' | |
| 9957 ' Note: When formatting a number ("int", "float", ' | |
| 9958 '"complex",\n' | |
| 9959 ' "decimal.Decimal" and subclasses) with the "n" type ' | |
| 9960 '(ex:\n' | |
| 9961 ' "\'{:n}\'.format(1234)"), the function temporarily ' | |
| 9962 'sets the\n' | |
| 9963 ' "LC_CTYPE" locale to the "LC_NUMERIC" locale to ' | |
| 9964 'decode\n' | |
| 9965 ' "decimal_point" and "thousands_sep" fields of ' | |
| 9966 '"localeconv()" if\n' | |
| 9967 ' they are non-ASCII or longer than 1 byte, and the ' | |
| 9968 '"LC_NUMERIC"\n' | |
| 9969 ' locale is different than the "LC_CTYPE" locale. This ' | |
| 9970 'temporary\n' | |
| 9971 ' change affects other threads.\n' | |
| 9972 '\n' | |
| 9973 ' Changed in version 3.7: When formatting a number with ' | |
| 9974 'the "n" type,\n' | |
| 9975 ' the function sets temporarily the "LC_CTYPE" locale to ' | |
| 9976 'the\n' | |
| 9977 ' "LC_NUMERIC" locale in some cases.\n' | |
| 9978 '\n' | |
| 9979 'str.format_map(mapping)\n' | |
| 9980 '\n' | |
| 9981 ' Similar to "str.format(**mapping)", except that ' | |
| 9982 '"mapping" is used\n' | |
| 9983 ' directly and not copied to a "dict". This is useful if ' | |
| 9984 'for example\n' | |
| 9985 ' "mapping" is a dict subclass:\n' | |
| 9986 '\n' | |
| 9987 ' >>> class Default(dict):\n' | |
| 9988 ' ... def __missing__(self, key):\n' | |
| 9989 ' ... return key\n' | |
| 9990 ' ...\n' | |
| 9991 " >>> '{name} was born in " | |
| 9992 "{country}'.format_map(Default(name='Guido'))\n" | |
| 9993 " 'Guido was born in country'\n" | |
| 9994 '\n' | |
| 9995 ' New in version 3.2.\n' | |
| 9996 '\n' | |
| 9997 'str.index(sub[, start[, end]])\n' | |
| 9998 '\n' | |
| 9999 ' Like "find()", but raise "ValueError" when the ' | |
| 10000 'substring is not\n' | |
| 10001 ' found.\n' | |
| 10002 '\n' | |
| 10003 'str.isalnum()\n' | |
| 10004 '\n' | |
| 10005 ' Return "True" if all characters in the string are ' | |
| 10006 'alphanumeric and\n' | |
| 10007 ' there is at least one character, "False" otherwise. A ' | |
| 10008 'character\n' | |
| 10009 ' "c" is alphanumeric if one of the following returns ' | |
| 10010 '"True":\n' | |
| 10011 ' "c.isalpha()", "c.isdecimal()", "c.isdigit()", or ' | |
| 10012 '"c.isnumeric()".\n' | |
| 10013 '\n' | |
| 10014 'str.isalpha()\n' | |
| 10015 '\n' | |
| 10016 ' Return "True" if all characters in the string are ' | |
| 10017 'alphabetic and\n' | |
| 10018 ' there is at least one character, "False" otherwise. ' | |
| 10019 'Alphabetic\n' | |
| 10020 ' characters are those characters defined in the Unicode ' | |
| 10021 'character\n' | |
| 10022 ' database as “Letter”, i.e., those with general category ' | |
| 10023 'property\n' | |
| 10024 ' being one of “Lm”, “Lt”, “Lu”, “Ll”, or “Lo”. Note ' | |
| 10025 'that this is\n' | |
| 10026 ' different from the “Alphabetic” property defined in the ' | |
| 10027 'Unicode\n' | |
| 10028 ' Standard.\n' | |
| 10029 '\n' | |
| 10030 'str.isascii()\n' | |
| 10031 '\n' | |
| 10032 ' Return "True" if the string is empty or all characters ' | |
| 10033 'in the\n' | |
| 10034 ' string are ASCII, "False" otherwise. ASCII characters ' | |
| 10035 'have code\n' | |
| 10036 ' points in the range U+0000-U+007F.\n' | |
| 10037 '\n' | |
| 10038 ' New in version 3.7.\n' | |
| 10039 '\n' | |
| 10040 'str.isdecimal()\n' | |
| 10041 '\n' | |
| 10042 ' Return "True" if all characters in the string are ' | |
| 10043 'decimal\n' | |
| 10044 ' characters and there is at least one character, "False" ' | |
| 10045 'otherwise.\n' | |
| 10046 ' Decimal characters are those that can be used to form ' | |
| 10047 'numbers in\n' | |
| 10048 ' base 10, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. ' | |
| 10049 'Formally a decimal\n' | |
| 10050 ' character is a character in the Unicode General ' | |
| 10051 'Category “Nd”.\n' | |
| 10052 '\n' | |
| 10053 'str.isdigit()\n' | |
| 10054 '\n' | |
| 10055 ' Return "True" if all characters in the string are ' | |
| 10056 'digits and there\n' | |
| 10057 ' is at least one character, "False" otherwise. Digits ' | |
| 10058 'include\n' | |
| 10059 ' decimal characters and digits that need special ' | |
| 10060 'handling, such as\n' | |
| 10061 ' the compatibility superscript digits. This covers ' | |
| 10062 'digits which\n' | |
| 10063 ' cannot be used to form numbers in base 10, like the ' | |
| 10064 'Kharosthi\n' | |
| 10065 ' numbers. Formally, a digit is a character that has the ' | |
| 10066 'property\n' | |
| 10067 ' value Numeric_Type=Digit or Numeric_Type=Decimal.\n' | |
| 10068 '\n' | |
| 10069 'str.isidentifier()\n' | |
| 10070 '\n' | |
| 10071 ' Return "True" if the string is a valid identifier ' | |
| 10072 'according to the\n' | |
| 10073 ' language definition, section Identifiers and keywords.\n' | |
| 10074 '\n' | |
| 10075 ' Call "keyword.iskeyword()" to test whether string "s" ' | |
| 10076 'is a reserved\n' | |
| 10077 ' identifier, such as "def" and "class".\n' | |
| 10078 '\n' | |
| 10079 ' Example:\n' | |
| 10080 '\n' | |
| 10081 ' >>> from keyword import iskeyword\n' | |
| 10082 '\n' | |
| 10083 " >>> 'hello'.isidentifier(), iskeyword('hello')\n" | |
| 10084 ' True, False\n' | |
| 10085 " >>> 'def'.isidentifier(), iskeyword('def')\n" | |
| 10086 ' True, True\n' | |
| 10087 '\n' | |
| 10088 'str.islower()\n' | |
| 10089 '\n' | |
| 10090 ' Return "True" if all cased characters [4] in the string ' | |
| 10091 'are\n' | |
| 10092 ' lowercase and there is at least one cased character, ' | |
| 10093 '"False"\n' | |
| 10094 ' otherwise.\n' | |
| 10095 '\n' | |
| 10096 'str.isnumeric()\n' | |
| 10097 '\n' | |
| 10098 ' Return "True" if all characters in the string are ' | |
| 10099 'numeric\n' | |
| 10100 ' characters, and there is at least one character, ' | |
| 10101 '"False" otherwise.\n' | |
| 10102 ' Numeric characters include digit characters, and all ' | |
| 10103 'characters\n' | |
| 10104 ' that have the Unicode numeric value property, e.g. ' | |
| 10105 'U+2155, VULGAR\n' | |
| 10106 ' FRACTION ONE FIFTH. Formally, numeric characters are ' | |
| 10107 'those with\n' | |
| 10108 ' the property value Numeric_Type=Digit, ' | |
| 10109 'Numeric_Type=Decimal or\n' | |
| 10110 ' Numeric_Type=Numeric.\n' | |
| 10111 '\n' | |
| 10112 'str.isprintable()\n' | |
| 10113 '\n' | |
| 10114 ' Return "True" if all characters in the string are ' | |
| 10115 'printable or the\n' | |
| 10116 ' string is empty, "False" otherwise. Nonprintable ' | |
| 10117 'characters are\n' | |
| 10118 ' those characters defined in the Unicode character ' | |
| 10119 'database as\n' | |
| 10120 ' “Other” or “Separator”, excepting the ASCII space ' | |
| 10121 '(0x20) which is\n' | |
| 10122 ' considered printable. (Note that printable characters ' | |
| 10123 'in this\n' | |
| 10124 ' context are those which should not be escaped when ' | |
| 10125 '"repr()" is\n' | |
| 10126 ' invoked on a string. It has no bearing on the handling ' | |
| 10127 'of strings\n' | |
| 10128 ' written to "sys.stdout" or "sys.stderr".)\n' | |
| 10129 '\n' | |
| 10130 'str.isspace()\n' | |
| 10131 '\n' | |
| 10132 ' Return "True" if there are only whitespace characters ' | |
| 10133 'in the string\n' | |
| 10134 ' and there is at least one character, "False" ' | |
| 10135 'otherwise.\n' | |
| 10136 '\n' | |
| 10137 ' A character is *whitespace* if in the Unicode character ' | |
| 10138 'database\n' | |
| 10139 ' (see "unicodedata"), either its general category is ' | |
| 10140 '"Zs"\n' | |
| 10141 ' (“Separator, space”), or its bidirectional class is one ' | |
| 10142 'of "WS",\n' | |
| 10143 ' "B", or "S".\n' | |
| 10144 '\n' | |
| 10145 'str.istitle()\n' | |
| 10146 '\n' | |
| 10147 ' Return "True" if the string is a titlecased string and ' | |
| 10148 'there is at\n' | |
| 10149 ' least one character, for example uppercase characters ' | |
| 10150 'may only\n' | |
| 10151 ' follow uncased characters and lowercase characters only ' | |
| 10152 'cased ones.\n' | |
| 10153 ' Return "False" otherwise.\n' | |
| 10154 '\n' | |
| 10155 'str.isupper()\n' | |
| 10156 '\n' | |
| 10157 ' Return "True" if all cased characters [4] in the string ' | |
| 10158 'are\n' | |
| 10159 ' uppercase and there is at least one cased character, ' | |
| 10160 '"False"\n' | |
| 10161 ' otherwise.\n' | |
| 10162 '\n' | |
| 10163 'str.join(iterable)\n' | |
| 10164 '\n' | |
| 10165 ' Return a string which is the concatenation of the ' | |
| 10166 'strings in\n' | |
| 10167 ' *iterable*. A "TypeError" will be raised if there are ' | |
| 10168 'any non-\n' | |
| 10169 ' string values in *iterable*, including "bytes" ' | |
| 10170 'objects. The\n' | |
| 10171 ' separator between elements is the string providing this ' | |
| 10172 'method.\n' | |
| 10173 '\n' | |
| 10174 'str.ljust(width[, fillchar])\n' | |
| 10175 '\n' | |
| 10176 ' Return the string left justified in a string of length ' | |
| 10177 '*width*.\n' | |
| 10178 ' Padding is done using the specified *fillchar* (default ' | |
| 10179 'is an ASCII\n' | |
| 10180 ' space). The original string is returned if *width* is ' | |
| 10181 'less than or\n' | |
| 10182 ' equal to "len(s)".\n' | |
| 10183 '\n' | |
| 10184 'str.lower()\n' | |
| 10185 '\n' | |
| 10186 ' Return a copy of the string with all the cased ' | |
| 10187 'characters [4]\n' | |
| 10188 ' converted to lowercase.\n' | |
| 10189 '\n' | |
| 10190 ' The lowercasing algorithm used is described in section ' | |
| 10191 '3.13 of the\n' | |
| 10192 ' Unicode Standard.\n' | |
| 10193 '\n' | |
| 10194 'str.lstrip([chars])\n' | |
| 10195 '\n' | |
| 10196 ' Return a copy of the string with leading characters ' | |
| 10197 'removed. The\n' | |
| 10198 ' *chars* argument is a string specifying the set of ' | |
| 10199 'characters to be\n' | |
| 10200 ' removed. If omitted or "None", the *chars* argument ' | |
| 10201 'defaults to\n' | |
| 10202 ' removing whitespace. The *chars* argument is not a ' | |
| 10203 'prefix; rather,\n' | |
| 10204 ' all combinations of its values are stripped:\n' | |
| 10205 '\n' | |
| 10206 " >>> ' spacious '.lstrip()\n" | |
| 10207 " 'spacious '\n" | |
| 10208 " >>> 'www.example.com'.lstrip('cmowz.')\n" | |
| 10209 " 'example.com'\n" | |
| 10210 '\n' | |
| 10211 'static str.maketrans(x[, y[, z]])\n' | |
| 10212 '\n' | |
| 10213 ' This static method returns a translation table usable ' | |
| 10214 'for\n' | |
| 10215 ' "str.translate()".\n' | |
| 10216 '\n' | |
| 10217 ' If there is only one argument, it must be a dictionary ' | |
| 10218 'mapping\n' | |
| 10219 ' Unicode ordinals (integers) or characters (strings of ' | |
| 10220 'length 1) to\n' | |
| 10221 ' Unicode ordinals, strings (of arbitrary lengths) or ' | |
| 10222 '"None".\n' | |
| 10223 ' Character keys will then be converted to ordinals.\n' | |
| 10224 '\n' | |
| 10225 ' If there are two arguments, they must be strings of ' | |
| 10226 'equal length,\n' | |
| 10227 ' and in the resulting dictionary, each character in x ' | |
| 10228 'will be mapped\n' | |
| 10229 ' to the character at the same position in y. If there ' | |
| 10230 'is a third\n' | |
| 10231 ' argument, it must be a string, whose characters will be ' | |
| 10232 'mapped to\n' | |
| 10233 ' "None" in the result.\n' | |
| 10234 '\n' | |
| 10235 'str.partition(sep)\n' | |
| 10236 '\n' | |
| 10237 ' Split the string at the first occurrence of *sep*, and ' | |
| 10238 'return a\n' | |
| 10239 ' 3-tuple containing the part before the separator, the ' | |
| 10240 'separator\n' | |
| 10241 ' itself, and the part after the separator. If the ' | |
| 10242 'separator is not\n' | |
| 10243 ' found, return a 3-tuple containing the string itself, ' | |
| 10244 'followed by\n' | |
| 10245 ' two empty strings.\n' | |
| 10246 '\n' | |
| 10247 'str.replace(old, new[, count])\n' | |
| 10248 '\n' | |
| 10249 ' Return a copy of the string with all occurrences of ' | |
| 10250 'substring *old*\n' | |
| 10251 ' replaced by *new*. If the optional argument *count* is ' | |
| 10252 'given, only\n' | |
| 10253 ' the first *count* occurrences are replaced.\n' | |
| 10254 '\n' | |
| 10255 'str.rfind(sub[, start[, end]])\n' | |
| 10256 '\n' | |
| 10257 ' Return the highest index in the string where substring ' | |
| 10258 '*sub* is\n' | |
| 10259 ' found, such that *sub* is contained within ' | |
| 10260 '"s[start:end]".\n' | |
| 10261 ' Optional arguments *start* and *end* are interpreted as ' | |
| 10262 'in slice\n' | |
| 10263 ' notation. Return "-1" on failure.\n' | |
| 10264 '\n' | |
| 10265 'str.rindex(sub[, start[, end]])\n' | |
| 10266 '\n' | |
| 10267 ' Like "rfind()" but raises "ValueError" when the ' | |
| 10268 'substring *sub* is\n' | |
| 10269 ' not found.\n' | |
| 10270 '\n' | |
| 10271 'str.rjust(width[, fillchar])\n' | |
| 10272 '\n' | |
| 10273 ' Return the string right justified in a string of length ' | |
| 10274 '*width*.\n' | |
| 10275 ' Padding is done using the specified *fillchar* (default ' | |
| 10276 'is an ASCII\n' | |
| 10277 ' space). The original string is returned if *width* is ' | |
| 10278 'less than or\n' | |
| 10279 ' equal to "len(s)".\n' | |
| 10280 '\n' | |
| 10281 'str.rpartition(sep)\n' | |
| 10282 '\n' | |
| 10283 ' Split the string at the last occurrence of *sep*, and ' | |
| 10284 'return a\n' | |
| 10285 ' 3-tuple containing the part before the separator, the ' | |
| 10286 'separator\n' | |
| 10287 ' itself, and the part after the separator. If the ' | |
| 10288 'separator is not\n' | |
| 10289 ' found, return a 3-tuple containing two empty strings, ' | |
| 10290 'followed by\n' | |
| 10291 ' the string itself.\n' | |
| 10292 '\n' | |
| 10293 'str.rsplit(sep=None, maxsplit=-1)\n' | |
| 10294 '\n' | |
| 10295 ' Return a list of the words in the string, using *sep* ' | |
| 10296 'as the\n' | |
| 10297 ' delimiter string. If *maxsplit* is given, at most ' | |
| 10298 '*maxsplit* splits\n' | |
| 10299 ' are done, the *rightmost* ones. If *sep* is not ' | |
| 10300 'specified or\n' | |
| 10301 ' "None", any whitespace string is a separator. Except ' | |
| 10302 'for splitting\n' | |
| 10303 ' from the right, "rsplit()" behaves like "split()" which ' | |
| 10304 'is\n' | |
| 10305 ' described in detail below.\n' | |
| 10306 '\n' | |
| 10307 'str.rstrip([chars])\n' | |
| 10308 '\n' | |
| 10309 ' Return a copy of the string with trailing characters ' | |
| 10310 'removed. The\n' | |
| 10311 ' *chars* argument is a string specifying the set of ' | |
| 10312 'characters to be\n' | |
| 10313 ' removed. If omitted or "None", the *chars* argument ' | |
| 10314 'defaults to\n' | |
| 10315 ' removing whitespace. The *chars* argument is not a ' | |
| 10316 'suffix; rather,\n' | |
| 10317 ' all combinations of its values are stripped:\n' | |
| 10318 '\n' | |
| 10319 " >>> ' spacious '.rstrip()\n" | |
| 10320 " ' spacious'\n" | |
| 10321 " >>> 'mississippi'.rstrip('ipz')\n" | |
| 10322 " 'mississ'\n" | |
| 10323 '\n' | |
| 10324 'str.split(sep=None, maxsplit=-1)\n' | |
| 10325 '\n' | |
| 10326 ' Return a list of the words in the string, using *sep* ' | |
| 10327 'as the\n' | |
| 10328 ' delimiter string. If *maxsplit* is given, at most ' | |
| 10329 '*maxsplit*\n' | |
| 10330 ' splits are done (thus, the list will have at most ' | |
| 10331 '"maxsplit+1"\n' | |
| 10332 ' elements). If *maxsplit* is not specified or "-1", ' | |
| 10333 'then there is\n' | |
| 10334 ' no limit on the number of splits (all possible splits ' | |
| 10335 'are made).\n' | |
| 10336 '\n' | |
| 10337 ' If *sep* is given, consecutive delimiters are not ' | |
| 10338 'grouped together\n' | |
| 10339 ' and are deemed to delimit empty strings (for example,\n' | |
| 10340 ' "\'1,,2\'.split(\',\')" returns "[\'1\', \'\', ' | |
| 10341 '\'2\']"). The *sep* argument\n' | |
| 10342 ' may consist of multiple characters (for example,\n' | |
| 10343 ' "\'1<>2<>3\'.split(\'<>\')" returns "[\'1\', \'2\', ' | |
| 10344 '\'3\']"). Splitting an\n' | |
| 10345 ' empty string with a specified separator returns ' | |
| 10346 '"[\'\']".\n' | |
| 10347 '\n' | |
| 10348 ' For example:\n' | |
| 10349 '\n' | |
| 10350 " >>> '1,2,3'.split(',')\n" | |
| 10351 " ['1', '2', '3']\n" | |
| 10352 " >>> '1,2,3'.split(',', maxsplit=1)\n" | |
| 10353 " ['1', '2,3']\n" | |
| 10354 " >>> '1,2,,3,'.split(',')\n" | |
| 10355 " ['1', '2', '', '3', '']\n" | |
| 10356 '\n' | |
| 10357 ' If *sep* is not specified or is "None", a different ' | |
| 10358 'splitting\n' | |
| 10359 ' algorithm is applied: runs of consecutive whitespace ' | |
| 10360 'are regarded\n' | |
| 10361 ' as a single separator, and the result will contain no ' | |
| 10362 'empty strings\n' | |
| 10363 ' at the start or end if the string has leading or ' | |
| 10364 'trailing\n' | |
| 10365 ' whitespace. Consequently, splitting an empty string or ' | |
| 10366 'a string\n' | |
| 10367 ' consisting of just whitespace with a "None" separator ' | |
| 10368 'returns "[]".\n' | |
| 10369 '\n' | |
| 10370 ' For example:\n' | |
| 10371 '\n' | |
| 10372 " >>> '1 2 3'.split()\n" | |
| 10373 " ['1', '2', '3']\n" | |
| 10374 " >>> '1 2 3'.split(maxsplit=1)\n" | |
| 10375 " ['1', '2 3']\n" | |
| 10376 " >>> ' 1 2 3 '.split()\n" | |
| 10377 " ['1', '2', '3']\n" | |
| 10378 '\n' | |
| 10379 'str.splitlines([keepends])\n' | |
| 10380 '\n' | |
| 10381 ' Return a list of the lines in the string, breaking at ' | |
| 10382 'line\n' | |
| 10383 ' boundaries. Line breaks are not included in the ' | |
| 10384 'resulting list\n' | |
| 10385 ' unless *keepends* is given and true.\n' | |
| 10386 '\n' | |
| 10387 ' This method splits on the following line boundaries. ' | |
| 10388 'In\n' | |
| 10389 ' particular, the boundaries are a superset of *universal ' | |
| 10390 'newlines*.\n' | |
| 10391 '\n' | |
| 10392 ' ' | |
| 10393 '+-------------------------+-------------------------------+\n' | |
| 10394 ' | Representation | ' | |
| 10395 'Description |\n' | |
| 10396 ' ' | |
| 10397 '|=========================|===============================|\n' | |
| 10398 ' | "\\n" | Line ' | |
| 10399 'Feed |\n' | |
| 10400 ' ' | |
| 10401 '+-------------------------+-------------------------------+\n' | |
| 10402 ' | "\\r" | Carriage ' | |
| 10403 'Return |\n' | |
| 10404 ' ' | |
| 10405 '+-------------------------+-------------------------------+\n' | |
| 10406 ' | "\\r\\n" | Carriage Return + Line ' | |
| 10407 'Feed |\n' | |
| 10408 ' ' | |
| 10409 '+-------------------------+-------------------------------+\n' | |
| 10410 ' | "\\v" or "\\x0b" | Line ' | |
| 10411 'Tabulation |\n' | |
| 10412 ' ' | |
| 10413 '+-------------------------+-------------------------------+\n' | |
| 10414 ' | "\\f" or "\\x0c" | Form ' | |
| 10415 'Feed |\n' | |
| 10416 ' ' | |
| 10417 '+-------------------------+-------------------------------+\n' | |
| 10418 ' | "\\x1c" | File ' | |
| 10419 'Separator |\n' | |
| 10420 ' ' | |
| 10421 '+-------------------------+-------------------------------+\n' | |
| 10422 ' | "\\x1d" | Group ' | |
| 10423 'Separator |\n' | |
| 10424 ' ' | |
| 10425 '+-------------------------+-------------------------------+\n' | |
| 10426 ' | "\\x1e" | Record ' | |
| 10427 'Separator |\n' | |
| 10428 ' ' | |
| 10429 '+-------------------------+-------------------------------+\n' | |
| 10430 ' | "\\x85" | Next Line (C1 Control ' | |
| 10431 'Code) |\n' | |
| 10432 ' ' | |
| 10433 '+-------------------------+-------------------------------+\n' | |
| 10434 ' | "\\u2028" | Line ' | |
| 10435 'Separator |\n' | |
| 10436 ' ' | |
| 10437 '+-------------------------+-------------------------------+\n' | |
| 10438 ' | "\\u2029" | Paragraph ' | |
| 10439 'Separator |\n' | |
| 10440 ' ' | |
| 10441 '+-------------------------+-------------------------------+\n' | |
| 10442 '\n' | |
| 10443 ' Changed in version 3.2: "\\v" and "\\f" added to list ' | |
| 10444 'of line\n' | |
| 10445 ' boundaries.\n' | |
| 10446 '\n' | |
| 10447 ' For example:\n' | |
| 10448 '\n' | |
| 10449 " >>> 'ab c\\n\\nde fg\\rkl\\r\\n'.splitlines()\n" | |
| 10450 " ['ab c', '', 'de fg', 'kl']\n" | |
| 10451 " >>> 'ab c\\n\\nde " | |
| 10452 "fg\\rkl\\r\\n'.splitlines(keepends=True)\n" | |
| 10453 " ['ab c\\n', '\\n', 'de fg\\r', 'kl\\r\\n']\n" | |
| 10454 '\n' | |
| 10455 ' Unlike "split()" when a delimiter string *sep* is ' | |
| 10456 'given, this\n' | |
| 10457 ' method returns an empty list for the empty string, and ' | |
| 10458 'a terminal\n' | |
| 10459 ' line break does not result in an extra line:\n' | |
| 10460 '\n' | |
| 10461 ' >>> "".splitlines()\n' | |
| 10462 ' []\n' | |
| 10463 ' >>> "One line\\n".splitlines()\n' | |
| 10464 " ['One line']\n" | |
| 10465 '\n' | |
| 10466 ' For comparison, "split(\'\\n\')" gives:\n' | |
| 10467 '\n' | |
| 10468 " >>> ''.split('\\n')\n" | |
| 10469 " ['']\n" | |
| 10470 " >>> 'Two lines\\n'.split('\\n')\n" | |
| 10471 " ['Two lines', '']\n" | |
| 10472 '\n' | |
| 10473 'str.startswith(prefix[, start[, end]])\n' | |
| 10474 '\n' | |
| 10475 ' Return "True" if string starts with the *prefix*, ' | |
| 10476 'otherwise return\n' | |
| 10477 ' "False". *prefix* can also be a tuple of prefixes to ' | |
| 10478 'look for.\n' | |
| 10479 ' With optional *start*, test string beginning at that ' | |
| 10480 'position.\n' | |
| 10481 ' With optional *end*, stop comparing string at that ' | |
| 10482 'position.\n' | |
| 10483 '\n' | |
| 10484 'str.strip([chars])\n' | |
| 10485 '\n' | |
| 10486 ' Return a copy of the string with the leading and ' | |
| 10487 'trailing\n' | |
| 10488 ' characters removed. The *chars* argument is a string ' | |
| 10489 'specifying the\n' | |
| 10490 ' set of characters to be removed. If omitted or "None", ' | |
| 10491 'the *chars*\n' | |
| 10492 ' argument defaults to removing whitespace. The *chars* ' | |
| 10493 'argument is\n' | |
| 10494 ' not a prefix or suffix; rather, all combinations of its ' | |
| 10495 'values are\n' | |
| 10496 ' stripped:\n' | |
| 10497 '\n' | |
| 10498 " >>> ' spacious '.strip()\n" | |
| 10499 " 'spacious'\n" | |
| 10500 " >>> 'www.example.com'.strip('cmowz.')\n" | |
| 10501 " 'example'\n" | |
| 10502 '\n' | |
| 10503 ' The outermost leading and trailing *chars* argument ' | |
| 10504 'values are\n' | |
| 10505 ' stripped from the string. Characters are removed from ' | |
| 10506 'the leading\n' | |
| 10507 ' end until reaching a string character that is not ' | |
| 10508 'contained in the\n' | |
| 10509 ' set of characters in *chars*. A similar action takes ' | |
| 10510 'place on the\n' | |
| 10511 ' trailing end. For example:\n' | |
| 10512 '\n' | |
| 10513 " >>> comment_string = '#....... Section 3.2.1 Issue " | |
| 10514 "#32 .......'\n" | |
| 10515 " >>> comment_string.strip('.#! ')\n" | |
| 10516 " 'Section 3.2.1 Issue #32'\n" | |
| 10517 '\n' | |
| 10518 'str.swapcase()\n' | |
| 10519 '\n' | |
| 10520 ' Return a copy of the string with uppercase characters ' | |
| 10521 'converted to\n' | |
| 10522 ' lowercase and vice versa. Note that it is not ' | |
| 10523 'necessarily true that\n' | |
| 10524 ' "s.swapcase().swapcase() == s".\n' | |
| 10525 '\n' | |
| 10526 'str.title()\n' | |
| 10527 '\n' | |
| 10528 ' Return a titlecased version of the string where words ' | |
| 10529 'start with an\n' | |
| 10530 ' uppercase character and the remaining characters are ' | |
| 10531 'lowercase.\n' | |
| 10532 '\n' | |
| 10533 ' For example:\n' | |
| 10534 '\n' | |
| 10535 " >>> 'Hello world'.title()\n" | |
| 10536 " 'Hello World'\n" | |
| 10537 '\n' | |
| 10538 ' The algorithm uses a simple language-independent ' | |
| 10539 'definition of a\n' | |
| 10540 ' word as groups of consecutive letters. The definition ' | |
| 10541 'works in\n' | |
| 10542 ' many contexts but it means that apostrophes in ' | |
| 10543 'contractions and\n' | |
| 10544 ' possessives form word boundaries, which may not be the ' | |
| 10545 'desired\n' | |
| 10546 ' result:\n' | |
| 10547 '\n' | |
| 10548 ' >>> "they\'re bill\'s friends from the UK".title()\n' | |
| 10549 ' "They\'Re Bill\'S Friends From The Uk"\n' | |
| 10550 '\n' | |
| 10551 ' A workaround for apostrophes can be constructed using ' | |
| 10552 'regular\n' | |
| 10553 ' expressions:\n' | |
| 10554 '\n' | |
| 10555 ' >>> import re\n' | |
| 10556 ' >>> def titlecase(s):\n' | |
| 10557 ' ... return re.sub(r"[A-Za-z]+(\'[A-Za-z]+)?",\n' | |
| 10558 ' ... lambda mo: ' | |
| 10559 'mo.group(0).capitalize(),\n' | |
| 10560 ' ... s)\n' | |
| 10561 ' ...\n' | |
| 10562 ' >>> titlecase("they\'re bill\'s friends.")\n' | |
| 10563 ' "They\'re Bill\'s Friends."\n' | |
| 10564 '\n' | |
| 10565 'str.translate(table)\n' | |
| 10566 '\n' | |
| 10567 ' Return a copy of the string in which each character has ' | |
| 10568 'been mapped\n' | |
| 10569 ' through the given translation table. The table must be ' | |
| 10570 'an object\n' | |
| 10571 ' that implements indexing via "__getitem__()", typically ' | |
| 10572 'a *mapping*\n' | |
| 10573 ' or *sequence*. When indexed by a Unicode ordinal (an ' | |
| 10574 'integer), the\n' | |
| 10575 ' table object can do any of the following: return a ' | |
| 10576 'Unicode ordinal\n' | |
| 10577 ' or a string, to map the character to one or more other ' | |
| 10578 'characters;\n' | |
| 10579 ' return "None", to delete the character from the return ' | |
| 10580 'string; or\n' | |
| 10581 ' raise a "LookupError" exception, to map the character ' | |
| 10582 'to itself.\n' | |
| 10583 '\n' | |
| 10584 ' You can use "str.maketrans()" to create a translation ' | |
| 10585 'map from\n' | |
| 10586 ' character-to-character mappings in different formats.\n' | |
| 10587 '\n' | |
| 10588 ' See also the "codecs" module for a more flexible ' | |
| 10589 'approach to custom\n' | |
| 10590 ' character mappings.\n' | |
| 10591 '\n' | |
| 10592 'str.upper()\n' | |
| 10593 '\n' | |
| 10594 ' Return a copy of the string with all the cased ' | |
| 10595 'characters [4]\n' | |
| 10596 ' converted to uppercase. Note that ' | |
| 10597 '"s.upper().isupper()" might be\n' | |
| 10598 ' "False" if "s" contains uncased characters or if the ' | |
| 10599 'Unicode\n' | |
| 10600 ' category of the resulting character(s) is not “Lu” ' | |
| 10601 '(Letter,\n' | |
| 10602 ' uppercase), but e.g. “Lt” (Letter, titlecase).\n' | |
| 10603 '\n' | |
| 10604 ' The uppercasing algorithm used is described in section ' | |
| 10605 '3.13 of the\n' | |
| 10606 ' Unicode Standard.\n' | |
| 10607 '\n' | |
| 10608 'str.zfill(width)\n' | |
| 10609 '\n' | |
| 10610 ' Return a copy of the string left filled with ASCII ' | |
| 10611 '"\'0\'" digits to\n' | |
| 10612 ' make a string of length *width*. A leading sign prefix\n' | |
| 10613 ' ("\'+\'"/"\'-\'") is handled by inserting the padding ' | |
| 10614 '*after* the sign\n' | |
| 10615 ' character rather than before. The original string is ' | |
| 10616 'returned if\n' | |
| 10617 ' *width* is less than or equal to "len(s)".\n' | |
| 10618 '\n' | |
| 10619 ' For example:\n' | |
| 10620 '\n' | |
| 10621 ' >>> "42".zfill(5)\n' | |
| 10622 " '00042'\n" | |
| 10623 ' >>> "-42".zfill(5)\n' | |
| 10624 " '-0042'\n", | |
| 10625 'strings': 'String and Bytes literals\n' | |
| 10626 '*************************\n' | |
| 10627 '\n' | |
| 10628 'String literals are described by the following lexical ' | |
| 10629 'definitions:\n' | |
| 10630 '\n' | |
| 10631 ' stringliteral ::= [stringprefix](shortstring | longstring)\n' | |
| 10632 ' stringprefix ::= "r" | "u" | "R" | "U" | "f" | "F"\n' | |
| 10633 ' | "fr" | "Fr" | "fR" | "FR" | "rf" | "rF" | ' | |
| 10634 '"Rf" | "RF"\n' | |
| 10635 ' shortstring ::= "\'" shortstringitem* "\'" | \'"\' ' | |
| 10636 'shortstringitem* \'"\'\n' | |
| 10637 ' longstring ::= "\'\'\'" longstringitem* "\'\'\'" | ' | |
| 10638 '\'"""\' longstringitem* \'"""\'\n' | |
| 10639 ' shortstringitem ::= shortstringchar | stringescapeseq\n' | |
| 10640 ' longstringitem ::= longstringchar | stringescapeseq\n' | |
| 10641 ' shortstringchar ::= <any source character except "\\" or ' | |
| 10642 'newline or the quote>\n' | |
| 10643 ' longstringchar ::= <any source character except "\\">\n' | |
| 10644 ' stringescapeseq ::= "\\" <any source character>\n' | |
| 10645 '\n' | |
| 10646 ' bytesliteral ::= bytesprefix(shortbytes | longbytes)\n' | |
| 10647 ' bytesprefix ::= "b" | "B" | "br" | "Br" | "bR" | "BR" | ' | |
| 10648 '"rb" | "rB" | "Rb" | "RB"\n' | |
| 10649 ' shortbytes ::= "\'" shortbytesitem* "\'" | \'"\' ' | |
| 10650 'shortbytesitem* \'"\'\n' | |
| 10651 ' longbytes ::= "\'\'\'" longbytesitem* "\'\'\'" | \'"""\' ' | |
| 10652 'longbytesitem* \'"""\'\n' | |
| 10653 ' shortbytesitem ::= shortbyteschar | bytesescapeseq\n' | |
| 10654 ' longbytesitem ::= longbyteschar | bytesescapeseq\n' | |
| 10655 ' shortbyteschar ::= <any ASCII character except "\\" or newline ' | |
| 10656 'or the quote>\n' | |
| 10657 ' longbyteschar ::= <any ASCII character except "\\">\n' | |
| 10658 ' bytesescapeseq ::= "\\" <any ASCII character>\n' | |
| 10659 '\n' | |
| 10660 'One syntactic restriction not indicated by these productions is ' | |
| 10661 'that\n' | |
| 10662 'whitespace is not allowed between the "stringprefix" or ' | |
| 10663 '"bytesprefix"\n' | |
| 10664 'and the rest of the literal. The source character set is defined ' | |
| 10665 'by\n' | |
| 10666 'the encoding declaration; it is UTF-8 if no encoding declaration ' | |
| 10667 'is\n' | |
| 10668 'given in the source file; see section Encoding declarations.\n' | |
| 10669 '\n' | |
| 10670 'In plain English: Both types of literals can be enclosed in ' | |
| 10671 'matching\n' | |
| 10672 'single quotes ("\'") or double quotes ("""). They can also be ' | |
| 10673 'enclosed\n' | |
| 10674 'in matching groups of three single or double quotes (these are\n' | |
| 10675 'generally referred to as *triple-quoted strings*). The ' | |
| 10676 'backslash\n' | |
| 10677 '("\\") character is used to escape characters that otherwise have ' | |
| 10678 'a\n' | |
| 10679 'special meaning, such as newline, backslash itself, or the quote\n' | |
| 10680 'character.\n' | |
| 10681 '\n' | |
| 10682 'Bytes literals are always prefixed with "\'b\'" or "\'B\'"; they ' | |
| 10683 'produce\n' | |
| 10684 'an instance of the "bytes" type instead of the "str" type. They ' | |
| 10685 'may\n' | |
| 10686 'only contain ASCII characters; bytes with a numeric value of 128 ' | |
| 10687 'or\n' | |
| 10688 'greater must be expressed with escapes.\n' | |
| 10689 '\n' | |
| 10690 'Both string and bytes literals may optionally be prefixed with a\n' | |
| 10691 'letter "\'r\'" or "\'R\'"; such strings are called *raw strings* ' | |
| 10692 'and treat\n' | |
| 10693 'backslashes as literal characters. As a result, in string ' | |
| 10694 'literals,\n' | |
| 10695 '"\'\\U\'" and "\'\\u\'" escapes in raw strings are not treated ' | |
| 10696 'specially.\n' | |
| 10697 'Given that Python 2.x’s raw unicode literals behave differently ' | |
| 10698 'than\n' | |
| 10699 'Python 3.x’s the "\'ur\'" syntax is not supported.\n' | |
| 10700 '\n' | |
| 10701 'New in version 3.3: The "\'rb\'" prefix of raw bytes literals has ' | |
| 10702 'been\n' | |
| 10703 'added as a synonym of "\'br\'".\n' | |
| 10704 '\n' | |
| 10705 'New in version 3.3: Support for the unicode legacy literal\n' | |
| 10706 '("u\'value\'") was reintroduced to simplify the maintenance of ' | |
| 10707 'dual\n' | |
| 10708 'Python 2.x and 3.x codebases. See **PEP 414** for more ' | |
| 10709 'information.\n' | |
| 10710 '\n' | |
| 10711 'A string literal with "\'f\'" or "\'F\'" in its prefix is a ' | |
| 10712 '*formatted\n' | |
| 10713 'string literal*; see Formatted string literals. The "\'f\'" may ' | |
| 10714 'be\n' | |
| 10715 'combined with "\'r\'", but not with "\'b\'" or "\'u\'", therefore ' | |
| 10716 'raw\n' | |
| 10717 'formatted strings are possible, but formatted bytes literals are ' | |
| 10718 'not.\n' | |
| 10719 '\n' | |
| 10720 'In triple-quoted literals, unescaped newlines and quotes are ' | |
| 10721 'allowed\n' | |
| 10722 '(and are retained), except that three unescaped quotes in a row\n' | |
| 10723 'terminate the literal. (A “quote” is the character used to open ' | |
| 10724 'the\n' | |
| 10725 'literal, i.e. either "\'" or """.)\n' | |
| 10726 '\n' | |
| 10727 'Unless an "\'r\'" or "\'R\'" prefix is present, escape sequences ' | |
| 10728 'in string\n' | |
| 10729 'and bytes literals are interpreted according to rules similar to ' | |
| 10730 'those\n' | |
| 10731 'used by Standard C. The recognized escape sequences are:\n' | |
| 10732 '\n' | |
| 10733 '+-------------------+-----------------------------------+---------+\n' | |
| 10734 '| Escape Sequence | Meaning | Notes ' | |
| 10735 '|\n' | |
| 10736 '|===================|===================================|=========|\n' | |
| 10737 '| "\\newline" | Backslash and newline ignored ' | |
| 10738 '| |\n' | |
| 10739 '+-------------------+-----------------------------------+---------+\n' | |
| 10740 '| "\\\\" | Backslash ("\\") ' | |
| 10741 '| |\n' | |
| 10742 '+-------------------+-----------------------------------+---------+\n' | |
| 10743 '| "\\\'" | Single quote ("\'") ' | |
| 10744 '| |\n' | |
| 10745 '+-------------------+-----------------------------------+---------+\n' | |
| 10746 '| "\\"" | Double quote (""") ' | |
| 10747 '| |\n' | |
| 10748 '+-------------------+-----------------------------------+---------+\n' | |
| 10749 '| "\\a" | ASCII Bell (BEL) ' | |
| 10750 '| |\n' | |
| 10751 '+-------------------+-----------------------------------+---------+\n' | |
| 10752 '| "\\b" | ASCII Backspace (BS) ' | |
| 10753 '| |\n' | |
| 10754 '+-------------------+-----------------------------------+---------+\n' | |
| 10755 '| "\\f" | ASCII Formfeed (FF) ' | |
| 10756 '| |\n' | |
| 10757 '+-------------------+-----------------------------------+---------+\n' | |
| 10758 '| "\\n" | ASCII Linefeed (LF) ' | |
| 10759 '| |\n' | |
| 10760 '+-------------------+-----------------------------------+---------+\n' | |
| 10761 '| "\\r" | ASCII Carriage Return (CR) ' | |
| 10762 '| |\n' | |
| 10763 '+-------------------+-----------------------------------+---------+\n' | |
| 10764 '| "\\t" | ASCII Horizontal Tab (TAB) ' | |
| 10765 '| |\n' | |
| 10766 '+-------------------+-----------------------------------+---------+\n' | |
| 10767 '| "\\v" | ASCII Vertical Tab (VT) ' | |
| 10768 '| |\n' | |
| 10769 '+-------------------+-----------------------------------+---------+\n' | |
| 10770 '| "\\ooo" | Character with octal value *ooo* | ' | |
| 10771 '(1,3) |\n' | |
| 10772 '+-------------------+-----------------------------------+---------+\n' | |
| 10773 '| "\\xhh" | Character with hex value *hh* | ' | |
| 10774 '(2,3) |\n' | |
| 10775 '+-------------------+-----------------------------------+---------+\n' | |
| 10776 '\n' | |
| 10777 'Escape sequences only recognized in string literals are:\n' | |
| 10778 '\n' | |
| 10779 '+-------------------+-----------------------------------+---------+\n' | |
| 10780 '| Escape Sequence | Meaning | Notes ' | |
| 10781 '|\n' | |
| 10782 '|===================|===================================|=========|\n' | |
| 10783 '| "\\N{name}" | Character named *name* in the | ' | |
| 10784 '(4) |\n' | |
| 10785 '| | Unicode database | ' | |
| 10786 '|\n' | |
| 10787 '+-------------------+-----------------------------------+---------+\n' | |
| 10788 '| "\\uxxxx" | Character with 16-bit hex value | ' | |
| 10789 '(5) |\n' | |
| 10790 '| | *xxxx* | ' | |
| 10791 '|\n' | |
| 10792 '+-------------------+-----------------------------------+---------+\n' | |
| 10793 '| "\\Uxxxxxxxx" | Character with 32-bit hex value | ' | |
| 10794 '(6) |\n' | |
| 10795 '| | *xxxxxxxx* | ' | |
| 10796 '|\n' | |
| 10797 '+-------------------+-----------------------------------+---------+\n' | |
| 10798 '\n' | |
| 10799 'Notes:\n' | |
| 10800 '\n' | |
| 10801 '1. As in Standard C, up to three octal digits are accepted.\n' | |
| 10802 '\n' | |
| 10803 '2. Unlike in Standard C, exactly two hex digits are required.\n' | |
| 10804 '\n' | |
| 10805 '3. In a bytes literal, hexadecimal and octal escapes denote the\n' | |
| 10806 ' byte with the given value. In a string literal, these escapes\n' | |
| 10807 ' denote a Unicode character with the given value.\n' | |
| 10808 '\n' | |
| 10809 '4. Changed in version 3.3: Support for name aliases [1] has been\n' | |
| 10810 ' added.\n' | |
| 10811 '\n' | |
| 10812 '5. Exactly four hex digits are required.\n' | |
| 10813 '\n' | |
| 10814 '6. Any Unicode character can be encoded this way. Exactly eight\n' | |
| 10815 ' hex digits are required.\n' | |
| 10816 '\n' | |
| 10817 'Unlike Standard C, all unrecognized escape sequences are left in ' | |
| 10818 'the\n' | |
| 10819 'string unchanged, i.e., *the backslash is left in the result*. ' | |
| 10820 '(This\n' | |
| 10821 'behavior is useful when debugging: if an escape sequence is ' | |
| 10822 'mistyped,\n' | |
| 10823 'the resulting output is more easily recognized as broken.) It is ' | |
| 10824 'also\n' | |
| 10825 'important to note that the escape sequences only recognized in ' | |
| 10826 'string\n' | |
| 10827 'literals fall into the category of unrecognized escapes for ' | |
| 10828 'bytes\n' | |
| 10829 'literals.\n' | |
| 10830 '\n' | |
| 10831 ' Changed in version 3.6: Unrecognized escape sequences produce ' | |
| 10832 'a\n' | |
| 10833 ' "DeprecationWarning". In a future Python version they will be ' | |
| 10834 'a\n' | |
| 10835 ' "SyntaxWarning" and eventually a "SyntaxError".\n' | |
| 10836 '\n' | |
| 10837 'Even in a raw literal, quotes can be escaped with a backslash, ' | |
| 10838 'but the\n' | |
| 10839 'backslash remains in the result; for example, "r"\\""" is a ' | |
| 10840 'valid\n' | |
| 10841 'string literal consisting of two characters: a backslash and a ' | |
| 10842 'double\n' | |
| 10843 'quote; "r"\\"" is not a valid string literal (even a raw string ' | |
| 10844 'cannot\n' | |
| 10845 'end in an odd number of backslashes). Specifically, *a raw ' | |
| 10846 'literal\n' | |
| 10847 'cannot end in a single backslash* (since the backslash would ' | |
| 10848 'escape\n' | |
| 10849 'the following quote character). Note also that a single ' | |
| 10850 'backslash\n' | |
| 10851 'followed by a newline is interpreted as those two characters as ' | |
| 10852 'part\n' | |
| 10853 'of the literal, *not* as a line continuation.\n', | |
| 10854 'subscriptions': 'Subscriptions\n' | |
| 10855 '*************\n' | |
| 10856 '\n' | |
| 10857 'A subscription selects an item of a sequence (string, tuple ' | |
| 10858 'or list)\n' | |
| 10859 'or mapping (dictionary) object:\n' | |
| 10860 '\n' | |
| 10861 ' subscription ::= primary "[" expression_list "]"\n' | |
| 10862 '\n' | |
| 10863 'The primary must evaluate to an object that supports ' | |
| 10864 'subscription\n' | |
| 10865 '(lists or dictionaries for example). User-defined objects ' | |
| 10866 'can support\n' | |
| 10867 'subscription by defining a "__getitem__()" method.\n' | |
| 10868 '\n' | |
| 10869 'For built-in objects, there are two types of objects that ' | |
| 10870 'support\n' | |
| 10871 'subscription:\n' | |
| 10872 '\n' | |
| 10873 'If the primary is a mapping, the expression list must ' | |
| 10874 'evaluate to an\n' | |
| 10875 'object whose value is one of the keys of the mapping, and ' | |
| 10876 'the\n' | |
| 10877 'subscription selects the value in the mapping that ' | |
| 10878 'corresponds to that\n' | |
| 10879 'key. (The expression list is a tuple except if it has ' | |
| 10880 'exactly one\n' | |
| 10881 'item.)\n' | |
| 10882 '\n' | |
| 10883 'If the primary is a sequence, the expression list must ' | |
| 10884 'evaluate to an\n' | |
| 10885 'integer or a slice (as discussed in the following ' | |
| 10886 'section).\n' | |
| 10887 '\n' | |
| 10888 'The formal syntax makes no special provision for negative ' | |
| 10889 'indices in\n' | |
| 10890 'sequences; however, built-in sequences all provide a ' | |
| 10891 '"__getitem__()"\n' | |
| 10892 'method that interprets negative indices by adding the ' | |
| 10893 'length of the\n' | |
| 10894 'sequence to the index (so that "x[-1]" selects the last ' | |
| 10895 'item of "x").\n' | |
| 10896 'The resulting value must be a nonnegative integer less than ' | |
| 10897 'the number\n' | |
| 10898 'of items in the sequence, and the subscription selects the ' | |
| 10899 'item whose\n' | |
| 10900 'index is that value (counting from zero). Since the support ' | |
| 10901 'for\n' | |
| 10902 'negative indices and slicing occurs in the object’s ' | |
| 10903 '"__getitem__()"\n' | |
| 10904 'method, subclasses overriding this method will need to ' | |
| 10905 'explicitly add\n' | |
| 10906 'that support.\n' | |
| 10907 '\n' | |
| 10908 'A string’s items are characters. A character is not a ' | |
| 10909 'separate data\n' | |
| 10910 'type but a string of exactly one character.\n', | |
| 10911 'truth': 'Truth Value Testing\n' | |
| 10912 '*******************\n' | |
| 10913 '\n' | |
| 10914 'Any object can be tested for truth value, for use in an "if" or\n' | |
| 10915 '"while" condition or as operand of the Boolean operations below.\n' | |
| 10916 '\n' | |
| 10917 'By default, an object is considered true unless its class defines\n' | |
| 10918 'either a "__bool__()" method that returns "False" or a "__len__()"\n' | |
| 10919 'method that returns zero, when called with the object. [1] Here ' | |
| 10920 'are\n' | |
| 10921 'most of the built-in objects considered false:\n' | |
| 10922 '\n' | |
| 10923 '* constants defined to be false: "None" and "False".\n' | |
| 10924 '\n' | |
| 10925 '* zero of any numeric type: "0", "0.0", "0j", "Decimal(0)",\n' | |
| 10926 ' "Fraction(0, 1)"\n' | |
| 10927 '\n' | |
| 10928 '* empty sequences and collections: "\'\'", "()", "[]", "{}", ' | |
| 10929 '"set()",\n' | |
| 10930 ' "range(0)"\n' | |
| 10931 '\n' | |
| 10932 'Operations and built-in functions that have a Boolean result ' | |
| 10933 'always\n' | |
| 10934 'return "0" or "False" for false and "1" or "True" for true, unless\n' | |
| 10935 'otherwise stated. (Important exception: the Boolean operations ' | |
| 10936 '"or"\n' | |
| 10937 'and "and" always return one of their operands.)\n', | |
| 10938 'try': 'The "try" statement\n' | |
| 10939 '*******************\n' | |
| 10940 '\n' | |
| 10941 'The "try" statement specifies exception handlers and/or cleanup code\n' | |
| 10942 'for a group of statements:\n' | |
| 10943 '\n' | |
| 10944 ' try_stmt ::= try1_stmt | try2_stmt\n' | |
| 10945 ' try1_stmt ::= "try" ":" suite\n' | |
| 10946 ' ("except" [expression ["as" identifier]] ":" ' | |
| 10947 'suite)+\n' | |
| 10948 ' ["else" ":" suite]\n' | |
| 10949 ' ["finally" ":" suite]\n' | |
| 10950 ' try2_stmt ::= "try" ":" suite\n' | |
| 10951 ' "finally" ":" suite\n' | |
| 10952 '\n' | |
| 10953 'The "except" clause(s) specify one or more exception handlers. When ' | |
| 10954 'no\n' | |
| 10955 'exception occurs in the "try" clause, no exception handler is\n' | |
| 10956 'executed. When an exception occurs in the "try" suite, a search for ' | |
| 10957 'an\n' | |
| 10958 'exception handler is started. This search inspects the except ' | |
| 10959 'clauses\n' | |
| 10960 'in turn until one is found that matches the exception. An ' | |
| 10961 'expression-\n' | |
| 10962 'less except clause, if present, must be last; it matches any\n' | |
| 10963 'exception. For an except clause with an expression, that expression\n' | |
| 10964 'is evaluated, and the clause matches the exception if the resulting\n' | |
| 10965 'object is “compatible” with the exception. An object is compatible\n' | |
| 10966 'with an exception if it is the class or a base class of the ' | |
| 10967 'exception\n' | |
| 10968 'object or a tuple containing an item compatible with the exception.\n' | |
| 10969 '\n' | |
| 10970 'If no except clause matches the exception, the search for an ' | |
| 10971 'exception\n' | |
| 10972 'handler continues in the surrounding code and on the invocation ' | |
| 10973 'stack.\n' | |
| 10974 '[1]\n' | |
| 10975 '\n' | |
| 10976 'If the evaluation of an expression in the header of an except clause\n' | |
| 10977 'raises an exception, the original search for a handler is canceled ' | |
| 10978 'and\n' | |
| 10979 'a search starts for the new exception in the surrounding code and on\n' | |
| 10980 'the call stack (it is treated as if the entire "try" statement ' | |
| 10981 'raised\n' | |
| 10982 'the exception).\n' | |
| 10983 '\n' | |
| 10984 'When a matching except clause is found, the exception is assigned to\n' | |
| 10985 'the target specified after the "as" keyword in that except clause, ' | |
| 10986 'if\n' | |
| 10987 'present, and the except clause’s suite is executed. All except\n' | |
| 10988 'clauses must have an executable block. When the end of this block ' | |
| 10989 'is\n' | |
| 10990 'reached, execution continues normally after the entire try ' | |
| 10991 'statement.\n' | |
| 10992 '(This means that if two nested handlers exist for the same ' | |
| 10993 'exception,\n' | |
| 10994 'and the exception occurs in the try clause of the inner handler, the\n' | |
| 10995 'outer handler will not handle the exception.)\n' | |
| 10996 '\n' | |
| 10997 'When an exception has been assigned using "as target", it is cleared\n' | |
| 10998 'at the end of the except clause. This is as if\n' | |
| 10999 '\n' | |
| 11000 ' except E as N:\n' | |
| 11001 ' foo\n' | |
| 11002 '\n' | |
| 11003 'was translated to\n' | |
| 11004 '\n' | |
| 11005 ' except E as N:\n' | |
| 11006 ' try:\n' | |
| 11007 ' foo\n' | |
| 11008 ' finally:\n' | |
| 11009 ' del N\n' | |
| 11010 '\n' | |
| 11011 'This means the exception must be assigned to a different name to be\n' | |
| 11012 'able to refer to it after the except clause. Exceptions are cleared\n' | |
| 11013 'because with the traceback attached to them, they form a reference\n' | |
| 11014 'cycle with the stack frame, keeping all locals in that frame alive\n' | |
| 11015 'until the next garbage collection occurs.\n' | |
| 11016 '\n' | |
| 11017 'Before an except clause’s suite is executed, details about the\n' | |
| 11018 'exception are stored in the "sys" module and can be accessed via\n' | |
| 11019 '"sys.exc_info()". "sys.exc_info()" returns a 3-tuple consisting of ' | |
| 11020 'the\n' | |
| 11021 'exception class, the exception instance and a traceback object (see\n' | |
| 11022 'section The standard type hierarchy) identifying the point in the\n' | |
| 11023 'program where the exception occurred. "sys.exc_info()" values are\n' | |
| 11024 'restored to their previous values (before the call) when returning\n' | |
| 11025 'from a function that handled an exception.\n' | |
| 11026 '\n' | |
| 11027 'The optional "else" clause is executed if the control flow leaves ' | |
| 11028 'the\n' | |
| 11029 '"try" suite, no exception was raised, and no "return", "continue", ' | |
| 11030 'or\n' | |
| 11031 '"break" statement was executed. Exceptions in the "else" clause are\n' | |
| 11032 'not handled by the preceding "except" clauses.\n' | |
| 11033 '\n' | |
| 11034 'If "finally" is present, it specifies a ‘cleanup’ handler. The ' | |
| 11035 '"try"\n' | |
| 11036 'clause is executed, including any "except" and "else" clauses. If ' | |
| 11037 'an\n' | |
| 11038 'exception occurs in any of the clauses and is not handled, the\n' | |
| 11039 'exception is temporarily saved. The "finally" clause is executed. ' | |
| 11040 'If\n' | |
| 11041 'there is a saved exception it is re-raised at the end of the ' | |
| 11042 '"finally"\n' | |
| 11043 'clause. If the "finally" clause raises another exception, the saved\n' | |
| 11044 'exception is set as the context of the new exception. If the ' | |
| 11045 '"finally"\n' | |
| 11046 'clause executes a "return", "break" or "continue" statement, the ' | |
| 11047 'saved\n' | |
| 11048 'exception is discarded:\n' | |
| 11049 '\n' | |
| 11050 ' >>> def f():\n' | |
| 11051 ' ... try:\n' | |
| 11052 ' ... 1/0\n' | |
| 11053 ' ... finally:\n' | |
| 11054 ' ... return 42\n' | |
| 11055 ' ...\n' | |
| 11056 ' >>> f()\n' | |
| 11057 ' 42\n' | |
| 11058 '\n' | |
| 11059 'The exception information is not available to the program during\n' | |
| 11060 'execution of the "finally" clause.\n' | |
| 11061 '\n' | |
| 11062 'When a "return", "break" or "continue" statement is executed in the\n' | |
| 11063 '"try" suite of a "try"…"finally" statement, the "finally" clause is\n' | |
| 11064 'also executed ‘on the way out.’\n' | |
| 11065 '\n' | |
| 11066 'The return value of a function is determined by the last "return"\n' | |
| 11067 'statement executed. Since the "finally" clause always executes, a\n' | |
| 11068 '"return" statement executed in the "finally" clause will always be ' | |
| 11069 'the\n' | |
| 11070 'last one executed:\n' | |
| 11071 '\n' | |
| 11072 ' >>> def foo():\n' | |
| 11073 ' ... try:\n' | |
| 11074 " ... return 'try'\n" | |
| 11075 ' ... finally:\n' | |
| 11076 " ... return 'finally'\n" | |
| 11077 ' ...\n' | |
| 11078 ' >>> foo()\n' | |
| 11079 " 'finally'\n" | |
| 11080 '\n' | |
| 11081 'Additional information on exceptions can be found in section\n' | |
| 11082 'Exceptions, and information on using the "raise" statement to ' | |
| 11083 'generate\n' | |
| 11084 'exceptions may be found in section The raise statement.\n' | |
| 11085 '\n' | |
| 11086 'Changed in version 3.8: Prior to Python 3.8, a "continue" statement\n' | |
| 11087 'was illegal in the "finally" clause due to a problem with the\n' | |
| 11088 'implementation.\n', | |
| 11089 'types': 'The standard type hierarchy\n' | |
| 11090 '***************************\n' | |
| 11091 '\n' | |
| 11092 'Below is a list of the types that are built into Python. ' | |
| 11093 'Extension\n' | |
| 11094 'modules (written in C, Java, or other languages, depending on the\n' | |
| 11095 'implementation) can define additional types. Future versions of\n' | |
| 11096 'Python may add types to the type hierarchy (e.g., rational ' | |
| 11097 'numbers,\n' | |
| 11098 'efficiently stored arrays of integers, etc.), although such ' | |
| 11099 'additions\n' | |
| 11100 'will often be provided via the standard library instead.\n' | |
| 11101 '\n' | |
| 11102 'Some of the type descriptions below contain a paragraph listing\n' | |
| 11103 '‘special attributes.’ These are attributes that provide access to ' | |
| 11104 'the\n' | |
| 11105 'implementation and are not intended for general use. Their ' | |
| 11106 'definition\n' | |
| 11107 'may change in the future.\n' | |
| 11108 '\n' | |
| 11109 'None\n' | |
| 11110 ' This type has a single value. There is a single object with ' | |
| 11111 'this\n' | |
| 11112 ' value. This object is accessed through the built-in name "None". ' | |
| 11113 'It\n' | |
| 11114 ' is used to signify the absence of a value in many situations, ' | |
| 11115 'e.g.,\n' | |
| 11116 ' it is returned from functions that don’t explicitly return\n' | |
| 11117 ' anything. Its truth value is false.\n' | |
| 11118 '\n' | |
| 11119 'NotImplemented\n' | |
| 11120 ' This type has a single value. There is a single object with ' | |
| 11121 'this\n' | |
| 11122 ' value. This object is accessed through the built-in name\n' | |
| 11123 ' "NotImplemented". Numeric methods and rich comparison methods\n' | |
| 11124 ' should return this value if they do not implement the operation ' | |
| 11125 'for\n' | |
| 11126 ' the operands provided. (The interpreter will then try the\n' | |
| 11127 ' reflected operation, or some other fallback, depending on the\n' | |
| 11128 ' operator.) Its truth value is true.\n' | |
| 11129 '\n' | |
| 11130 ' See Implementing the arithmetic operations for more details.\n' | |
| 11131 '\n' | |
| 11132 'Ellipsis\n' | |
| 11133 ' This type has a single value. There is a single object with ' | |
| 11134 'this\n' | |
| 11135 ' value. This object is accessed through the literal "..." or the\n' | |
| 11136 ' built-in name "Ellipsis". Its truth value is true.\n' | |
| 11137 '\n' | |
| 11138 '"numbers.Number"\n' | |
| 11139 ' These are created by numeric literals and returned as results ' | |
| 11140 'by\n' | |
| 11141 ' arithmetic operators and arithmetic built-in functions. ' | |
| 11142 'Numeric\n' | |
| 11143 ' objects are immutable; once created their value never changes.\n' | |
| 11144 ' Python numbers are of course strongly related to mathematical\n' | |
| 11145 ' numbers, but subject to the limitations of numerical ' | |
| 11146 'representation\n' | |
| 11147 ' in computers.\n' | |
| 11148 '\n' | |
| 11149 ' Python distinguishes between integers, floating point numbers, ' | |
| 11150 'and\n' | |
| 11151 ' complex numbers:\n' | |
| 11152 '\n' | |
| 11153 ' "numbers.Integral"\n' | |
| 11154 ' These represent elements from the mathematical set of ' | |
| 11155 'integers\n' | |
| 11156 ' (positive and negative).\n' | |
| 11157 '\n' | |
| 11158 ' There are two types of integers:\n' | |
| 11159 '\n' | |
| 11160 ' Integers ("int")\n' | |
| 11161 '\n' | |
| 11162 ' These represent numbers in an unlimited range, subject to\n' | |
| 11163 ' available (virtual) memory only. For the purpose of ' | |
| 11164 'shift\n' | |
| 11165 ' and mask operations, a binary representation is assumed, ' | |
| 11166 'and\n' | |
| 11167 ' negative numbers are represented in a variant of 2’s\n' | |
| 11168 ' complement which gives the illusion of an infinite string ' | |
| 11169 'of\n' | |
| 11170 ' sign bits extending to the left.\n' | |
| 11171 '\n' | |
| 11172 ' Booleans ("bool")\n' | |
| 11173 ' These represent the truth values False and True. The two\n' | |
| 11174 ' objects representing the values "False" and "True" are ' | |
| 11175 'the\n' | |
| 11176 ' only Boolean objects. The Boolean type is a subtype of ' | |
| 11177 'the\n' | |
| 11178 ' integer type, and Boolean values behave like the values 0 ' | |
| 11179 'and\n' | |
| 11180 ' 1, respectively, in almost all contexts, the exception ' | |
| 11181 'being\n' | |
| 11182 ' that when converted to a string, the strings ""False"" or\n' | |
| 11183 ' ""True"" are returned, respectively.\n' | |
| 11184 '\n' | |
| 11185 ' The rules for integer representation are intended to give ' | |
| 11186 'the\n' | |
| 11187 ' most meaningful interpretation of shift and mask operations\n' | |
| 11188 ' involving negative integers.\n' | |
| 11189 '\n' | |
| 11190 ' "numbers.Real" ("float")\n' | |
| 11191 ' These represent machine-level double precision floating ' | |
| 11192 'point\n' | |
| 11193 ' numbers. You are at the mercy of the underlying machine\n' | |
| 11194 ' architecture (and C or Java implementation) for the accepted\n' | |
| 11195 ' range and handling of overflow. Python does not support ' | |
| 11196 'single-\n' | |
| 11197 ' precision floating point numbers; the savings in processor ' | |
| 11198 'and\n' | |
| 11199 ' memory usage that are usually the reason for using these are\n' | |
| 11200 ' dwarfed by the overhead of using objects in Python, so there ' | |
| 11201 'is\n' | |
| 11202 ' no reason to complicate the language with two kinds of ' | |
| 11203 'floating\n' | |
| 11204 ' point numbers.\n' | |
| 11205 '\n' | |
| 11206 ' "numbers.Complex" ("complex")\n' | |
| 11207 ' These represent complex numbers as a pair of machine-level\n' | |
| 11208 ' double precision floating point numbers. The same caveats ' | |
| 11209 'apply\n' | |
| 11210 ' as for floating point numbers. The real and imaginary parts ' | |
| 11211 'of a\n' | |
| 11212 ' complex number "z" can be retrieved through the read-only\n' | |
| 11213 ' attributes "z.real" and "z.imag".\n' | |
| 11214 '\n' | |
| 11215 'Sequences\n' | |
| 11216 ' These represent finite ordered sets indexed by non-negative\n' | |
| 11217 ' numbers. The built-in function "len()" returns the number of ' | |
| 11218 'items\n' | |
| 11219 ' of a sequence. When the length of a sequence is *n*, the index ' | |
| 11220 'set\n' | |
| 11221 ' contains the numbers 0, 1, …, *n*-1. Item *i* of sequence *a* ' | |
| 11222 'is\n' | |
| 11223 ' selected by "a[i]".\n' | |
| 11224 '\n' | |
| 11225 ' Sequences also support slicing: "a[i:j]" selects all items with\n' | |
| 11226 ' index *k* such that *i* "<=" *k* "<" *j*. When used as an\n' | |
| 11227 ' expression, a slice is a sequence of the same type. This ' | |
| 11228 'implies\n' | |
| 11229 ' that the index set is renumbered so that it starts at 0.\n' | |
| 11230 '\n' | |
| 11231 ' Some sequences also support “extended slicing” with a third ' | |
| 11232 '“step”\n' | |
| 11233 ' parameter: "a[i:j:k]" selects all items of *a* with index *x* ' | |
| 11234 'where\n' | |
| 11235 ' "x = i + n*k", *n* ">=" "0" and *i* "<=" *x* "<" *j*.\n' | |
| 11236 '\n' | |
| 11237 ' Sequences are distinguished according to their mutability:\n' | |
| 11238 '\n' | |
| 11239 ' Immutable sequences\n' | |
| 11240 ' An object of an immutable sequence type cannot change once it ' | |
| 11241 'is\n' | |
| 11242 ' created. (If the object contains references to other ' | |
| 11243 'objects,\n' | |
| 11244 ' these other objects may be mutable and may be changed; ' | |
| 11245 'however,\n' | |
| 11246 ' the collection of objects directly referenced by an ' | |
| 11247 'immutable\n' | |
| 11248 ' object cannot change.)\n' | |
| 11249 '\n' | |
| 11250 ' The following types are immutable sequences:\n' | |
| 11251 '\n' | |
| 11252 ' Strings\n' | |
| 11253 ' A string is a sequence of values that represent Unicode ' | |
| 11254 'code\n' | |
| 11255 ' points. All the code points in the range "U+0000 - ' | |
| 11256 'U+10FFFF"\n' | |
| 11257 ' can be represented in a string. Python doesn’t have a ' | |
| 11258 '"char"\n' | |
| 11259 ' type; instead, every code point in the string is ' | |
| 11260 'represented\n' | |
| 11261 ' as a string object with length "1". The built-in ' | |
| 11262 'function\n' | |
| 11263 ' "ord()" converts a code point from its string form to an\n' | |
| 11264 ' integer in the range "0 - 10FFFF"; "chr()" converts an\n' | |
| 11265 ' integer in the range "0 - 10FFFF" to the corresponding ' | |
| 11266 'length\n' | |
| 11267 ' "1" string object. "str.encode()" can be used to convert ' | |
| 11268 'a\n' | |
| 11269 ' "str" to "bytes" using the given text encoding, and\n' | |
| 11270 ' "bytes.decode()" can be used to achieve the opposite.\n' | |
| 11271 '\n' | |
| 11272 ' Tuples\n' | |
| 11273 ' The items of a tuple are arbitrary Python objects. Tuples ' | |
| 11274 'of\n' | |
| 11275 ' two or more items are formed by comma-separated lists of\n' | |
| 11276 ' expressions. A tuple of one item (a ‘singleton’) can be\n' | |
| 11277 ' formed by affixing a comma to an expression (an expression ' | |
| 11278 'by\n' | |
| 11279 ' itself does not create a tuple, since parentheses must be\n' | |
| 11280 ' usable for grouping of expressions). An empty tuple can ' | |
| 11281 'be\n' | |
| 11282 ' formed by an empty pair of parentheses.\n' | |
| 11283 '\n' | |
| 11284 ' Bytes\n' | |
| 11285 ' A bytes object is an immutable array. The items are ' | |
| 11286 '8-bit\n' | |
| 11287 ' bytes, represented by integers in the range 0 <= x < 256.\n' | |
| 11288 ' Bytes literals (like "b\'abc\'") and the built-in ' | |
| 11289 '"bytes()"\n' | |
| 11290 ' constructor can be used to create bytes objects. Also, ' | |
| 11291 'bytes\n' | |
| 11292 ' objects can be decoded to strings via the "decode()" ' | |
| 11293 'method.\n' | |
| 11294 '\n' | |
| 11295 ' Mutable sequences\n' | |
| 11296 ' Mutable sequences can be changed after they are created. ' | |
| 11297 'The\n' | |
| 11298 ' subscription and slicing notations can be used as the target ' | |
| 11299 'of\n' | |
| 11300 ' assignment and "del" (delete) statements.\n' | |
| 11301 '\n' | |
| 11302 ' There are currently two intrinsic mutable sequence types:\n' | |
| 11303 '\n' | |
| 11304 ' Lists\n' | |
| 11305 ' The items of a list are arbitrary Python objects. Lists ' | |
| 11306 'are\n' | |
| 11307 ' formed by placing a comma-separated list of expressions ' | |
| 11308 'in\n' | |
| 11309 ' square brackets. (Note that there are no special cases ' | |
| 11310 'needed\n' | |
| 11311 ' to form lists of length 0 or 1.)\n' | |
| 11312 '\n' | |
| 11313 ' Byte Arrays\n' | |
| 11314 ' A bytearray object is a mutable array. They are created ' | |
| 11315 'by\n' | |
| 11316 ' the built-in "bytearray()" constructor. Aside from being\n' | |
| 11317 ' mutable (and hence unhashable), byte arrays otherwise ' | |
| 11318 'provide\n' | |
| 11319 ' the same interface and functionality as immutable "bytes"\n' | |
| 11320 ' objects.\n' | |
| 11321 '\n' | |
| 11322 ' The extension module "array" provides an additional example ' | |
| 11323 'of a\n' | |
| 11324 ' mutable sequence type, as does the "collections" module.\n' | |
| 11325 '\n' | |
| 11326 'Set types\n' | |
| 11327 ' These represent unordered, finite sets of unique, immutable\n' | |
| 11328 ' objects. As such, they cannot be indexed by any subscript. ' | |
| 11329 'However,\n' | |
| 11330 ' they can be iterated over, and the built-in function "len()"\n' | |
| 11331 ' returns the number of items in a set. Common uses for sets are ' | |
| 11332 'fast\n' | |
| 11333 ' membership testing, removing duplicates from a sequence, and\n' | |
| 11334 ' computing mathematical operations such as intersection, union,\n' | |
| 11335 ' difference, and symmetric difference.\n' | |
| 11336 '\n' | |
| 11337 ' For set elements, the same immutability rules apply as for\n' | |
| 11338 ' dictionary keys. Note that numeric types obey the normal rules ' | |
| 11339 'for\n' | |
| 11340 ' numeric comparison: if two numbers compare equal (e.g., "1" and\n' | |
| 11341 ' "1.0"), only one of them can be contained in a set.\n' | |
| 11342 '\n' | |
| 11343 ' There are currently two intrinsic set types:\n' | |
| 11344 '\n' | |
| 11345 ' Sets\n' | |
| 11346 ' These represent a mutable set. They are created by the ' | |
| 11347 'built-in\n' | |
| 11348 ' "set()" constructor and can be modified afterwards by ' | |
| 11349 'several\n' | |
| 11350 ' methods, such as "add()".\n' | |
| 11351 '\n' | |
| 11352 ' Frozen sets\n' | |
| 11353 ' These represent an immutable set. They are created by the\n' | |
| 11354 ' built-in "frozenset()" constructor. As a frozenset is ' | |
| 11355 'immutable\n' | |
| 11356 ' and *hashable*, it can be used again as an element of ' | |
| 11357 'another\n' | |
| 11358 ' set, or as a dictionary key.\n' | |
| 11359 '\n' | |
| 11360 'Mappings\n' | |
| 11361 ' These represent finite sets of objects indexed by arbitrary ' | |
| 11362 'index\n' | |
| 11363 ' sets. The subscript notation "a[k]" selects the item indexed by ' | |
| 11364 '"k"\n' | |
| 11365 ' from the mapping "a"; this can be used in expressions and as ' | |
| 11366 'the\n' | |
| 11367 ' target of assignments or "del" statements. The built-in ' | |
| 11368 'function\n' | |
| 11369 ' "len()" returns the number of items in a mapping.\n' | |
| 11370 '\n' | |
| 11371 ' There is currently a single intrinsic mapping type:\n' | |
| 11372 '\n' | |
| 11373 ' Dictionaries\n' | |
| 11374 ' These represent finite sets of objects indexed by nearly\n' | |
| 11375 ' arbitrary values. The only types of values not acceptable ' | |
| 11376 'as\n' | |
| 11377 ' keys are values containing lists or dictionaries or other\n' | |
| 11378 ' mutable types that are compared by value rather than by ' | |
| 11379 'object\n' | |
| 11380 ' identity, the reason being that the efficient implementation ' | |
| 11381 'of\n' | |
| 11382 ' dictionaries requires a key’s hash value to remain constant.\n' | |
| 11383 ' Numeric types used for keys obey the normal rules for ' | |
| 11384 'numeric\n' | |
| 11385 ' comparison: if two numbers compare equal (e.g., "1" and ' | |
| 11386 '"1.0")\n' | |
| 11387 ' then they can be used interchangeably to index the same\n' | |
| 11388 ' dictionary entry.\n' | |
| 11389 '\n' | |
| 11390 ' Dictionaries are mutable; they can be created by the "{...}"\n' | |
| 11391 ' notation (see section Dictionary displays).\n' | |
| 11392 '\n' | |
| 11393 ' The extension modules "dbm.ndbm" and "dbm.gnu" provide\n' | |
| 11394 ' additional examples of mapping types, as does the ' | |
| 11395 '"collections"\n' | |
| 11396 ' module.\n' | |
| 11397 '\n' | |
| 11398 'Callable types\n' | |
| 11399 ' These are the types to which the function call operation (see\n' | |
| 11400 ' section Calls) can be applied:\n' | |
| 11401 '\n' | |
| 11402 ' User-defined functions\n' | |
| 11403 ' A user-defined function object is created by a function\n' | |
| 11404 ' definition (see section Function definitions). It should be\n' | |
| 11405 ' called with an argument list containing the same number of ' | |
| 11406 'items\n' | |
| 11407 ' as the function’s formal parameter list.\n' | |
| 11408 '\n' | |
| 11409 ' Special attributes:\n' | |
| 11410 '\n' | |
| 11411 ' ' | |
| 11412 '+---------------------------+---------------------------------+-------------+\n' | |
| 11413 ' | Attribute | Meaning ' | |
| 11414 '| |\n' | |
| 11415 ' ' | |
| 11416 '|===========================|=================================|=============|\n' | |
| 11417 ' | "__doc__" | The function’s documentation ' | |
| 11418 '| Writable |\n' | |
| 11419 ' | | string, or "None" if ' | |
| 11420 '| |\n' | |
| 11421 ' | | unavailable; not inherited by ' | |
| 11422 '| |\n' | |
| 11423 ' | | subclasses. ' | |
| 11424 '| |\n' | |
| 11425 ' ' | |
| 11426 '+---------------------------+---------------------------------+-------------+\n' | |
| 11427 ' | "__name__" | The function’s name. ' | |
| 11428 '| Writable |\n' | |
| 11429 ' ' | |
| 11430 '+---------------------------+---------------------------------+-------------+\n' | |
| 11431 ' | "__qualname__" | The function’s *qualified ' | |
| 11432 '| Writable |\n' | |
| 11433 ' | | name*. New in version 3.3. ' | |
| 11434 '| |\n' | |
| 11435 ' ' | |
| 11436 '+---------------------------+---------------------------------+-------------+\n' | |
| 11437 ' | "__module__" | The name of the module the ' | |
| 11438 '| Writable |\n' | |
| 11439 ' | | function was defined in, or ' | |
| 11440 '| |\n' | |
| 11441 ' | | "None" if unavailable. ' | |
| 11442 '| |\n' | |
| 11443 ' ' | |
| 11444 '+---------------------------+---------------------------------+-------------+\n' | |
| 11445 ' | "__defaults__" | A tuple containing default ' | |
| 11446 '| Writable |\n' | |
| 11447 ' | | argument values for those ' | |
| 11448 '| |\n' | |
| 11449 ' | | arguments that have defaults, ' | |
| 11450 '| |\n' | |
| 11451 ' | | or "None" if no arguments have ' | |
| 11452 '| |\n' | |
| 11453 ' | | a default value. ' | |
| 11454 '| |\n' | |
| 11455 ' ' | |
| 11456 '+---------------------------+---------------------------------+-------------+\n' | |
| 11457 ' | "__code__" | The code object representing ' | |
| 11458 '| Writable |\n' | |
| 11459 ' | | the compiled function body. ' | |
| 11460 '| |\n' | |
| 11461 ' ' | |
| 11462 '+---------------------------+---------------------------------+-------------+\n' | |
| 11463 ' | "__globals__" | A reference to the dictionary ' | |
| 11464 '| Read-only |\n' | |
| 11465 ' | | that holds the function’s ' | |
| 11466 '| |\n' | |
| 11467 ' | | global variables — the global ' | |
| 11468 '| |\n' | |
| 11469 ' | | namespace of the module in ' | |
| 11470 '| |\n' | |
| 11471 ' | | which the function was defined. ' | |
| 11472 '| |\n' | |
| 11473 ' ' | |
| 11474 '+---------------------------+---------------------------------+-------------+\n' | |
| 11475 ' | "__dict__" | The namespace supporting ' | |
| 11476 '| Writable |\n' | |
| 11477 ' | | arbitrary function attributes. ' | |
| 11478 '| |\n' | |
| 11479 ' ' | |
| 11480 '+---------------------------+---------------------------------+-------------+\n' | |
| 11481 ' | "__closure__" | "None" or a tuple of cells that ' | |
| 11482 '| Read-only |\n' | |
| 11483 ' | | contain bindings for the ' | |
| 11484 '| |\n' | |
| 11485 ' | | function’s free variables. See ' | |
| 11486 '| |\n' | |
| 11487 ' | | below for information on the ' | |
| 11488 '| |\n' | |
| 11489 ' | | "cell_contents" attribute. ' | |
| 11490 '| |\n' | |
| 11491 ' ' | |
| 11492 '+---------------------------+---------------------------------+-------------+\n' | |
| 11493 ' | "__annotations__" | A dict containing annotations ' | |
| 11494 '| Writable |\n' | |
| 11495 ' | | of parameters. The keys of the ' | |
| 11496 '| |\n' | |
| 11497 ' | | dict are the parameter names, ' | |
| 11498 '| |\n' | |
| 11499 ' | | and "\'return\'" for the ' | |
| 11500 'return | |\n' | |
| 11501 ' | | annotation, if provided. ' | |
| 11502 '| |\n' | |
| 11503 ' ' | |
| 11504 '+---------------------------+---------------------------------+-------------+\n' | |
| 11505 ' | "__kwdefaults__" | A dict containing defaults for ' | |
| 11506 '| Writable |\n' | |
| 11507 ' | | keyword-only parameters. ' | |
| 11508 '| |\n' | |
| 11509 ' ' | |
| 11510 '+---------------------------+---------------------------------+-------------+\n' | |
| 11511 '\n' | |
| 11512 ' Most of the attributes labelled “Writable” check the type of ' | |
| 11513 'the\n' | |
| 11514 ' assigned value.\n' | |
| 11515 '\n' | |
| 11516 ' Function objects also support getting and setting arbitrary\n' | |
| 11517 ' attributes, which can be used, for example, to attach ' | |
| 11518 'metadata\n' | |
| 11519 ' to functions. Regular attribute dot-notation is used to get ' | |
| 11520 'and\n' | |
| 11521 ' set such attributes. *Note that the current implementation ' | |
| 11522 'only\n' | |
| 11523 ' supports function attributes on user-defined functions. ' | |
| 11524 'Function\n' | |
| 11525 ' attributes on built-in functions may be supported in the\n' | |
| 11526 ' future.*\n' | |
| 11527 '\n' | |
| 11528 ' A cell object has the attribute "cell_contents". This can be\n' | |
| 11529 ' used to get the value of the cell, as well as set the value.\n' | |
| 11530 '\n' | |
| 11531 ' Additional information about a function’s definition can be\n' | |
| 11532 ' retrieved from its code object; see the description of ' | |
| 11533 'internal\n' | |
| 11534 ' types below. The "cell" type can be accessed in the "types"\n' | |
| 11535 ' module.\n' | |
| 11536 '\n' | |
| 11537 ' Instance methods\n' | |
| 11538 ' An instance method object combines a class, a class instance ' | |
| 11539 'and\n' | |
| 11540 ' any callable object (normally a user-defined function).\n' | |
| 11541 '\n' | |
| 11542 ' Special read-only attributes: "__self__" is the class ' | |
| 11543 'instance\n' | |
| 11544 ' object, "__func__" is the function object; "__doc__" is the\n' | |
| 11545 ' method’s documentation (same as "__func__.__doc__"); ' | |
| 11546 '"__name__"\n' | |
| 11547 ' is the method name (same as "__func__.__name__"); ' | |
| 11548 '"__module__"\n' | |
| 11549 ' is the name of the module the method was defined in, or ' | |
| 11550 '"None"\n' | |
| 11551 ' if unavailable.\n' | |
| 11552 '\n' | |
| 11553 ' Methods also support accessing (but not setting) the ' | |
| 11554 'arbitrary\n' | |
| 11555 ' function attributes on the underlying function object.\n' | |
| 11556 '\n' | |
| 11557 ' User-defined method objects may be created when getting an\n' | |
| 11558 ' attribute of a class (perhaps via an instance of that class), ' | |
| 11559 'if\n' | |
| 11560 ' that attribute is a user-defined function object or a class\n' | |
| 11561 ' method object.\n' | |
| 11562 '\n' | |
| 11563 ' When an instance method object is created by retrieving a ' | |
| 11564 'user-\n' | |
| 11565 ' defined function object from a class via one of its ' | |
| 11566 'instances,\n' | |
| 11567 ' its "__self__" attribute is the instance, and the method ' | |
| 11568 'object\n' | |
| 11569 ' is said to be bound. The new method’s "__func__" attribute ' | |
| 11570 'is\n' | |
| 11571 ' the original function object.\n' | |
| 11572 '\n' | |
| 11573 ' When an instance method object is created by retrieving a ' | |
| 11574 'class\n' | |
| 11575 ' method object from a class or instance, its "__self__" ' | |
| 11576 'attribute\n' | |
| 11577 ' is the class itself, and its "__func__" attribute is the\n' | |
| 11578 ' function object underlying the class method.\n' | |
| 11579 '\n' | |
| 11580 ' When an instance method object is called, the underlying\n' | |
| 11581 ' function ("__func__") is called, inserting the class ' | |
| 11582 'instance\n' | |
| 11583 ' ("__self__") in front of the argument list. For instance, ' | |
| 11584 'when\n' | |
| 11585 ' "C" is a class which contains a definition for a function ' | |
| 11586 '"f()",\n' | |
| 11587 ' and "x" is an instance of "C", calling "x.f(1)" is equivalent ' | |
| 11588 'to\n' | |
| 11589 ' calling "C.f(x, 1)".\n' | |
| 11590 '\n' | |
| 11591 ' When an instance method object is derived from a class ' | |
| 11592 'method\n' | |
| 11593 ' object, the “class instance” stored in "__self__" will ' | |
| 11594 'actually\n' | |
| 11595 ' be the class itself, so that calling either "x.f(1)" or ' | |
| 11596 '"C.f(1)"\n' | |
| 11597 ' is equivalent to calling "f(C,1)" where "f" is the ' | |
| 11598 'underlying\n' | |
| 11599 ' function.\n' | |
| 11600 '\n' | |
| 11601 ' Note that the transformation from function object to ' | |
| 11602 'instance\n' | |
| 11603 ' method object happens each time the attribute is retrieved ' | |
| 11604 'from\n' | |
| 11605 ' the instance. In some cases, a fruitful optimization is to\n' | |
| 11606 ' assign the attribute to a local variable and call that local\n' | |
| 11607 ' variable. Also notice that this transformation only happens ' | |
| 11608 'for\n' | |
| 11609 ' user-defined functions; other callable objects (and all non-\n' | |
| 11610 ' callable objects) are retrieved without transformation. It ' | |
| 11611 'is\n' | |
| 11612 ' also important to note that user-defined functions which are\n' | |
| 11613 ' attributes of a class instance are not converted to bound\n' | |
| 11614 ' methods; this *only* happens when the function is an ' | |
| 11615 'attribute\n' | |
| 11616 ' of the class.\n' | |
| 11617 '\n' | |
| 11618 ' Generator functions\n' | |
| 11619 ' A function or method which uses the "yield" statement (see\n' | |
| 11620 ' section The yield statement) is called a *generator ' | |
| 11621 'function*.\n' | |
| 11622 ' Such a function, when called, always returns an iterator ' | |
| 11623 'object\n' | |
| 11624 ' which can be used to execute the body of the function: ' | |
| 11625 'calling\n' | |
| 11626 ' the iterator’s "iterator.__next__()" method will cause the\n' | |
| 11627 ' function to execute until it provides a value using the ' | |
| 11628 '"yield"\n' | |
| 11629 ' statement. When the function executes a "return" statement ' | |
| 11630 'or\n' | |
| 11631 ' falls off the end, a "StopIteration" exception is raised and ' | |
| 11632 'the\n' | |
| 11633 ' iterator will have reached the end of the set of values to ' | |
| 11634 'be\n' | |
| 11635 ' returned.\n' | |
| 11636 '\n' | |
| 11637 ' Coroutine functions\n' | |
| 11638 ' A function or method which is defined using "async def" is\n' | |
| 11639 ' called a *coroutine function*. Such a function, when ' | |
| 11640 'called,\n' | |
| 11641 ' returns a *coroutine* object. It may contain "await"\n' | |
| 11642 ' expressions, as well as "async with" and "async for" ' | |
| 11643 'statements.\n' | |
| 11644 ' See also the Coroutine Objects section.\n' | |
| 11645 '\n' | |
| 11646 ' Asynchronous generator functions\n' | |
| 11647 ' A function or method which is defined using "async def" and\n' | |
| 11648 ' which uses the "yield" statement is called a *asynchronous\n' | |
| 11649 ' generator function*. Such a function, when called, returns ' | |
| 11650 'an\n' | |
| 11651 ' asynchronous iterator object which can be used in an "async ' | |
| 11652 'for"\n' | |
| 11653 ' statement to execute the body of the function.\n' | |
| 11654 '\n' | |
| 11655 ' Calling the asynchronous iterator’s "aiterator.__anext__()"\n' | |
| 11656 ' method will return an *awaitable* which when awaited will\n' | |
| 11657 ' execute until it provides a value using the "yield" ' | |
| 11658 'expression.\n' | |
| 11659 ' When the function executes an empty "return" statement or ' | |
| 11660 'falls\n' | |
| 11661 ' off the end, a "StopAsyncIteration" exception is raised and ' | |
| 11662 'the\n' | |
| 11663 ' asynchronous iterator will have reached the end of the set ' | |
| 11664 'of\n' | |
| 11665 ' values to be yielded.\n' | |
| 11666 '\n' | |
| 11667 ' Built-in functions\n' | |
| 11668 ' A built-in function object is a wrapper around a C function.\n' | |
| 11669 ' Examples of built-in functions are "len()" and "math.sin()"\n' | |
| 11670 ' ("math" is a standard built-in module). The number and type ' | |
| 11671 'of\n' | |
| 11672 ' the arguments are determined by the C function. Special ' | |
| 11673 'read-\n' | |
| 11674 ' only attributes: "__doc__" is the function’s documentation\n' | |
| 11675 ' string, or "None" if unavailable; "__name__" is the ' | |
| 11676 'function’s\n' | |
| 11677 ' name; "__self__" is set to "None" (but see the next item);\n' | |
| 11678 ' "__module__" is the name of the module the function was ' | |
| 11679 'defined\n' | |
| 11680 ' in or "None" if unavailable.\n' | |
| 11681 '\n' | |
| 11682 ' Built-in methods\n' | |
| 11683 ' This is really a different disguise of a built-in function, ' | |
| 11684 'this\n' | |
| 11685 ' time containing an object passed to the C function as an\n' | |
| 11686 ' implicit extra argument. An example of a built-in method is\n' | |
| 11687 ' "alist.append()", assuming *alist* is a list object. In this\n' | |
| 11688 ' case, the special read-only attribute "__self__" is set to ' | |
| 11689 'the\n' | |
| 11690 ' object denoted by *alist*.\n' | |
| 11691 '\n' | |
| 11692 ' Classes\n' | |
| 11693 ' Classes are callable. These objects normally act as ' | |
| 11694 'factories\n' | |
| 11695 ' for new instances of themselves, but variations are possible ' | |
| 11696 'for\n' | |
| 11697 ' class types that override "__new__()". The arguments of the\n' | |
| 11698 ' call are passed to "__new__()" and, in the typical case, to\n' | |
| 11699 ' "__init__()" to initialize the new instance.\n' | |
| 11700 '\n' | |
| 11701 ' Class Instances\n' | |
| 11702 ' Instances of arbitrary classes can be made callable by ' | |
| 11703 'defining\n' | |
| 11704 ' a "__call__()" method in their class.\n' | |
| 11705 '\n' | |
| 11706 'Modules\n' | |
| 11707 ' Modules are a basic organizational unit of Python code, and are\n' | |
| 11708 ' created by the import system as invoked either by the "import"\n' | |
| 11709 ' statement, or by calling functions such as\n' | |
| 11710 ' "importlib.import_module()" and built-in "__import__()". A ' | |
| 11711 'module\n' | |
| 11712 ' object has a namespace implemented by a dictionary object (this ' | |
| 11713 'is\n' | |
| 11714 ' the dictionary referenced by the "__globals__" attribute of\n' | |
| 11715 ' functions defined in the module). Attribute references are\n' | |
| 11716 ' translated to lookups in this dictionary, e.g., "m.x" is ' | |
| 11717 'equivalent\n' | |
| 11718 ' to "m.__dict__["x"]". A module object does not contain the code\n' | |
| 11719 ' object used to initialize the module (since it isn’t needed ' | |
| 11720 'once\n' | |
| 11721 ' the initialization is done).\n' | |
| 11722 '\n' | |
| 11723 ' Attribute assignment updates the module’s namespace dictionary,\n' | |
| 11724 ' e.g., "m.x = 1" is equivalent to "m.__dict__["x"] = 1".\n' | |
| 11725 '\n' | |
| 11726 ' Predefined (writable) attributes: "__name__" is the module’s ' | |
| 11727 'name;\n' | |
| 11728 ' "__doc__" is the module’s documentation string, or "None" if\n' | |
| 11729 ' unavailable; "__annotations__" (optional) is a dictionary\n' | |
| 11730 ' containing *variable annotations* collected during module body\n' | |
| 11731 ' execution; "__file__" is the pathname of the file from which ' | |
| 11732 'the\n' | |
| 11733 ' module was loaded, if it was loaded from a file. The "__file__"\n' | |
| 11734 ' attribute may be missing for certain types of modules, such as ' | |
| 11735 'C\n' | |
| 11736 ' modules that are statically linked into the interpreter; for\n' | |
| 11737 ' extension modules loaded dynamically from a shared library, it ' | |
| 11738 'is\n' | |
| 11739 ' the pathname of the shared library file.\n' | |
| 11740 '\n' | |
| 11741 ' Special read-only attribute: "__dict__" is the module’s ' | |
| 11742 'namespace\n' | |
| 11743 ' as a dictionary object.\n' | |
| 11744 '\n' | |
| 11745 ' **CPython implementation detail:** Because of the way CPython\n' | |
| 11746 ' clears module dictionaries, the module dictionary will be ' | |
| 11747 'cleared\n' | |
| 11748 ' when the module falls out of scope even if the dictionary still ' | |
| 11749 'has\n' | |
| 11750 ' live references. To avoid this, copy the dictionary or keep ' | |
| 11751 'the\n' | |
| 11752 ' module around while using its dictionary directly.\n' | |
| 11753 '\n' | |
| 11754 'Custom classes\n' | |
| 11755 ' Custom class types are typically created by class definitions ' | |
| 11756 '(see\n' | |
| 11757 ' section Class definitions). A class has a namespace implemented ' | |
| 11758 'by\n' | |
| 11759 ' a dictionary object. Class attribute references are translated ' | |
| 11760 'to\n' | |
| 11761 ' lookups in this dictionary, e.g., "C.x" is translated to\n' | |
| 11762 ' "C.__dict__["x"]" (although there are a number of hooks which ' | |
| 11763 'allow\n' | |
| 11764 ' for other means of locating attributes). When the attribute name ' | |
| 11765 'is\n' | |
| 11766 ' not found there, the attribute search continues in the base\n' | |
| 11767 ' classes. This search of the base classes uses the C3 method\n' | |
| 11768 ' resolution order which behaves correctly even in the presence ' | |
| 11769 'of\n' | |
| 11770 ' ‘diamond’ inheritance structures where there are multiple\n' | |
| 11771 ' inheritance paths leading back to a common ancestor. Additional\n' | |
| 11772 ' details on the C3 MRO used by Python can be found in the\n' | |
| 11773 ' documentation accompanying the 2.3 release at\n' | |
| 11774 ' https://www.python.org/download/releases/2.3/mro/.\n' | |
| 11775 '\n' | |
| 11776 ' When a class attribute reference (for class "C", say) would ' | |
| 11777 'yield a\n' | |
| 11778 ' class method object, it is transformed into an instance method\n' | |
| 11779 ' object whose "__self__" attribute is "C". When it would yield ' | |
| 11780 'a\n' | |
| 11781 ' static method object, it is transformed into the object wrapped ' | |
| 11782 'by\n' | |
| 11783 ' the static method object. See section Implementing Descriptors ' | |
| 11784 'for\n' | |
| 11785 ' another way in which attributes retrieved from a class may ' | |
| 11786 'differ\n' | |
| 11787 ' from those actually contained in its "__dict__".\n' | |
| 11788 '\n' | |
| 11789 ' Class attribute assignments update the class’s dictionary, ' | |
| 11790 'never\n' | |
| 11791 ' the dictionary of a base class.\n' | |
| 11792 '\n' | |
| 11793 ' A class object can be called (see above) to yield a class ' | |
| 11794 'instance\n' | |
| 11795 ' (see below).\n' | |
| 11796 '\n' | |
| 11797 ' Special attributes: "__name__" is the class name; "__module__" ' | |
| 11798 'is\n' | |
| 11799 ' the module name in which the class was defined; "__dict__" is ' | |
| 11800 'the\n' | |
| 11801 ' dictionary containing the class’s namespace; "__bases__" is a ' | |
| 11802 'tuple\n' | |
| 11803 ' containing the base classes, in the order of their occurrence ' | |
| 11804 'in\n' | |
| 11805 ' the base class list; "__doc__" is the class’s documentation ' | |
| 11806 'string,\n' | |
| 11807 ' or "None" if undefined; "__annotations__" (optional) is a\n' | |
| 11808 ' dictionary containing *variable annotations* collected during ' | |
| 11809 'class\n' | |
| 11810 ' body execution.\n' | |
| 11811 '\n' | |
| 11812 'Class instances\n' | |
| 11813 ' A class instance is created by calling a class object (see ' | |
| 11814 'above).\n' | |
| 11815 ' A class instance has a namespace implemented as a dictionary ' | |
| 11816 'which\n' | |
| 11817 ' is the first place in which attribute references are searched.\n' | |
| 11818 ' When an attribute is not found there, and the instance’s class ' | |
| 11819 'has\n' | |
| 11820 ' an attribute by that name, the search continues with the class\n' | |
| 11821 ' attributes. If a class attribute is found that is a ' | |
| 11822 'user-defined\n' | |
| 11823 ' function object, it is transformed into an instance method ' | |
| 11824 'object\n' | |
| 11825 ' whose "__self__" attribute is the instance. Static method and\n' | |
| 11826 ' class method objects are also transformed; see above under\n' | |
| 11827 ' “Classes”. See section Implementing Descriptors for another way ' | |
| 11828 'in\n' | |
| 11829 ' which attributes of a class retrieved via its instances may ' | |
| 11830 'differ\n' | |
| 11831 ' from the objects actually stored in the class’s "__dict__". If ' | |
| 11832 'no\n' | |
| 11833 ' class attribute is found, and the object’s class has a\n' | |
| 11834 ' "__getattr__()" method, that is called to satisfy the lookup.\n' | |
| 11835 '\n' | |
| 11836 ' Attribute assignments and deletions update the instance’s\n' | |
| 11837 ' dictionary, never a class’s dictionary. If the class has a\n' | |
| 11838 ' "__setattr__()" or "__delattr__()" method, this is called ' | |
| 11839 'instead\n' | |
| 11840 ' of updating the instance dictionary directly.\n' | |
| 11841 '\n' | |
| 11842 ' Class instances can pretend to be numbers, sequences, or ' | |
| 11843 'mappings\n' | |
| 11844 ' if they have methods with certain special names. See section\n' | |
| 11845 ' Special method names.\n' | |
| 11846 '\n' | |
| 11847 ' Special attributes: "__dict__" is the attribute dictionary;\n' | |
| 11848 ' "__class__" is the instance’s class.\n' | |
| 11849 '\n' | |
| 11850 'I/O objects (also known as file objects)\n' | |
| 11851 ' A *file object* represents an open file. Various shortcuts are\n' | |
| 11852 ' available to create file objects: the "open()" built-in ' | |
| 11853 'function,\n' | |
| 11854 ' and also "os.popen()", "os.fdopen()", and the "makefile()" ' | |
| 11855 'method\n' | |
| 11856 ' of socket objects (and perhaps by other functions or methods\n' | |
| 11857 ' provided by extension modules).\n' | |
| 11858 '\n' | |
| 11859 ' The objects "sys.stdin", "sys.stdout" and "sys.stderr" are\n' | |
| 11860 ' initialized to file objects corresponding to the interpreter’s\n' | |
| 11861 ' standard input, output and error streams; they are all open in ' | |
| 11862 'text\n' | |
| 11863 ' mode and therefore follow the interface defined by the\n' | |
| 11864 ' "io.TextIOBase" abstract class.\n' | |
| 11865 '\n' | |
| 11866 'Internal types\n' | |
| 11867 ' A few types used internally by the interpreter are exposed to ' | |
| 11868 'the\n' | |
| 11869 ' user. Their definitions may change with future versions of the\n' | |
| 11870 ' interpreter, but they are mentioned here for completeness.\n' | |
| 11871 '\n' | |
| 11872 ' Code objects\n' | |
| 11873 ' Code objects represent *byte-compiled* executable Python ' | |
| 11874 'code,\n' | |
| 11875 ' or *bytecode*. The difference between a code object and a\n' | |
| 11876 ' function object is that the function object contains an ' | |
| 11877 'explicit\n' | |
| 11878 ' reference to the function’s globals (the module in which it ' | |
| 11879 'was\n' | |
| 11880 ' defined), while a code object contains no context; also the\n' | |
| 11881 ' default argument values are stored in the function object, ' | |
| 11882 'not\n' | |
| 11883 ' in the code object (because they represent values calculated ' | |
| 11884 'at\n' | |
| 11885 ' run-time). Unlike function objects, code objects are ' | |
| 11886 'immutable\n' | |
| 11887 ' and contain no references (directly or indirectly) to ' | |
| 11888 'mutable\n' | |
| 11889 ' objects.\n' | |
| 11890 '\n' | |
| 11891 ' Special read-only attributes: "co_name" gives the function ' | |
| 11892 'name;\n' | |
| 11893 ' "co_argcount" is the total number of positional arguments\n' | |
| 11894 ' (including positional-only arguments and arguments with ' | |
| 11895 'default\n' | |
| 11896 ' values); "co_posonlyargcount" is the number of ' | |
| 11897 'positional-only\n' | |
| 11898 ' arguments (including arguments with default values);\n' | |
| 11899 ' "co_kwonlyargcount" is the number of keyword-only arguments\n' | |
| 11900 ' (including arguments with default values); "co_nlocals" is ' | |
| 11901 'the\n' | |
| 11902 ' number of local variables used by the function (including\n' | |
| 11903 ' arguments); "co_varnames" is a tuple containing the names of ' | |
| 11904 'the\n' | |
| 11905 ' local variables (starting with the argument names);\n' | |
| 11906 ' "co_cellvars" is a tuple containing the names of local ' | |
| 11907 'variables\n' | |
| 11908 ' that are referenced by nested functions; "co_freevars" is a\n' | |
| 11909 ' tuple containing the names of free variables; "co_code" is a\n' | |
| 11910 ' string representing the sequence of bytecode instructions;\n' | |
| 11911 ' "co_consts" is a tuple containing the literals used by the\n' | |
| 11912 ' bytecode; "co_names" is a tuple containing the names used by ' | |
| 11913 'the\n' | |
| 11914 ' bytecode; "co_filename" is the filename from which the code ' | |
| 11915 'was\n' | |
| 11916 ' compiled; "co_firstlineno" is the first line number of the\n' | |
| 11917 ' function; "co_lnotab" is a string encoding the mapping from\n' | |
| 11918 ' bytecode offsets to line numbers (for details see the source\n' | |
| 11919 ' code of the interpreter); "co_stacksize" is the required ' | |
| 11920 'stack\n' | |
| 11921 ' size (including local variables); "co_flags" is an integer\n' | |
| 11922 ' encoding a number of flags for the interpreter.\n' | |
| 11923 '\n' | |
| 11924 ' The following flag bits are defined for "co_flags": bit ' | |
| 11925 '"0x04"\n' | |
| 11926 ' is set if the function uses the "*arguments" syntax to accept ' | |
| 11927 'an\n' | |
| 11928 ' arbitrary number of positional arguments; bit "0x08" is set ' | |
| 11929 'if\n' | |
| 11930 ' the function uses the "**keywords" syntax to accept ' | |
| 11931 'arbitrary\n' | |
| 11932 ' keyword arguments; bit "0x20" is set if the function is a\n' | |
| 11933 ' generator.\n' | |
| 11934 '\n' | |
| 11935 ' Future feature declarations ("from __future__ import ' | |
| 11936 'division")\n' | |
| 11937 ' also use bits in "co_flags" to indicate whether a code ' | |
| 11938 'object\n' | |
| 11939 ' was compiled with a particular feature enabled: bit "0x2000" ' | |
| 11940 'is\n' | |
| 11941 ' set if the function was compiled with future division ' | |
| 11942 'enabled;\n' | |
| 11943 ' bits "0x10" and "0x1000" were used in earlier versions of\n' | |
| 11944 ' Python.\n' | |
| 11945 '\n' | |
| 11946 ' Other bits in "co_flags" are reserved for internal use.\n' | |
| 11947 '\n' | |
| 11948 ' If a code object represents a function, the first item in\n' | |
| 11949 ' "co_consts" is the documentation string of the function, or\n' | |
| 11950 ' "None" if undefined.\n' | |
| 11951 '\n' | |
| 11952 ' Frame objects\n' | |
| 11953 ' Frame objects represent execution frames. They may occur in\n' | |
| 11954 ' traceback objects (see below), and are also passed to ' | |
| 11955 'registered\n' | |
| 11956 ' trace functions.\n' | |
| 11957 '\n' | |
| 11958 ' Special read-only attributes: "f_back" is to the previous ' | |
| 11959 'stack\n' | |
| 11960 ' frame (towards the caller), or "None" if this is the bottom\n' | |
| 11961 ' stack frame; "f_code" is the code object being executed in ' | |
| 11962 'this\n' | |
| 11963 ' frame; "f_locals" is the dictionary used to look up local\n' | |
| 11964 ' variables; "f_globals" is used for global variables;\n' | |
| 11965 ' "f_builtins" is used for built-in (intrinsic) names; ' | |
| 11966 '"f_lasti"\n' | |
| 11967 ' gives the precise instruction (this is an index into the\n' | |
| 11968 ' bytecode string of the code object).\n' | |
| 11969 '\n' | |
| 11970 ' Special writable attributes: "f_trace", if not "None", is a\n' | |
| 11971 ' function called for various events during code execution ' | |
| 11972 '(this\n' | |
| 11973 ' is used by the debugger). Normally an event is triggered for\n' | |
| 11974 ' each new source line - this can be disabled by setting\n' | |
| 11975 ' "f_trace_lines" to "False".\n' | |
| 11976 '\n' | |
| 11977 ' Implementations *may* allow per-opcode events to be requested ' | |
| 11978 'by\n' | |
| 11979 ' setting "f_trace_opcodes" to "True". Note that this may lead ' | |
| 11980 'to\n' | |
| 11981 ' undefined interpreter behaviour if exceptions raised by the\n' | |
| 11982 ' trace function escape to the function being traced.\n' | |
| 11983 '\n' | |
| 11984 ' "f_lineno" is the current line number of the frame — writing ' | |
| 11985 'to\n' | |
| 11986 ' this from within a trace function jumps to the given line ' | |
| 11987 '(only\n' | |
| 11988 ' for the bottom-most frame). A debugger can implement a Jump\n' | |
| 11989 ' command (aka Set Next Statement) by writing to f_lineno.\n' | |
| 11990 '\n' | |
| 11991 ' Frame objects support one method:\n' | |
| 11992 '\n' | |
| 11993 ' frame.clear()\n' | |
| 11994 '\n' | |
| 11995 ' This method clears all references to local variables held ' | |
| 11996 'by\n' | |
| 11997 ' the frame. Also, if the frame belonged to a generator, ' | |
| 11998 'the\n' | |
| 11999 ' generator is finalized. This helps break reference ' | |
| 12000 'cycles\n' | |
| 12001 ' involving frame objects (for example when catching an\n' | |
| 12002 ' exception and storing its traceback for later use).\n' | |
| 12003 '\n' | |
| 12004 ' "RuntimeError" is raised if the frame is currently ' | |
| 12005 'executing.\n' | |
| 12006 '\n' | |
| 12007 ' New in version 3.4.\n' | |
| 12008 '\n' | |
| 12009 ' Traceback objects\n' | |
| 12010 ' Traceback objects represent a stack trace of an exception. ' | |
| 12011 'A\n' | |
| 12012 ' traceback object is implicitly created when an exception ' | |
| 12013 'occurs,\n' | |
| 12014 ' and may also be explicitly created by calling\n' | |
| 12015 ' "types.TracebackType".\n' | |
| 12016 '\n' | |
| 12017 ' For implicitly created tracebacks, when the search for an\n' | |
| 12018 ' exception handler unwinds the execution stack, at each ' | |
| 12019 'unwound\n' | |
| 12020 ' level a traceback object is inserted in front of the current\n' | |
| 12021 ' traceback. When an exception handler is entered, the stack\n' | |
| 12022 ' trace is made available to the program. (See section The try\n' | |
| 12023 ' statement.) It is accessible as the third item of the tuple\n' | |
| 12024 ' returned by "sys.exc_info()", and as the "__traceback__"\n' | |
| 12025 ' attribute of the caught exception.\n' | |
| 12026 '\n' | |
| 12027 ' When the program contains no suitable handler, the stack ' | |
| 12028 'trace\n' | |
| 12029 ' is written (nicely formatted) to the standard error stream; ' | |
| 12030 'if\n' | |
| 12031 ' the interpreter is interactive, it is also made available to ' | |
| 12032 'the\n' | |
| 12033 ' user as "sys.last_traceback".\n' | |
| 12034 '\n' | |
| 12035 ' For explicitly created tracebacks, it is up to the creator ' | |
| 12036 'of\n' | |
| 12037 ' the traceback to determine how the "tb_next" attributes ' | |
| 12038 'should\n' | |
| 12039 ' be linked to form a full stack trace.\n' | |
| 12040 '\n' | |
| 12041 ' Special read-only attributes: "tb_frame" points to the ' | |
| 12042 'execution\n' | |
| 12043 ' frame of the current level; "tb_lineno" gives the line ' | |
| 12044 'number\n' | |
| 12045 ' where the exception occurred; "tb_lasti" indicates the ' | |
| 12046 'precise\n' | |
| 12047 ' instruction. The line number and last instruction in the\n' | |
| 12048 ' traceback may differ from the line number of its frame object ' | |
| 12049 'if\n' | |
| 12050 ' the exception occurred in a "try" statement with no matching\n' | |
| 12051 ' except clause or with a finally clause.\n' | |
| 12052 '\n' | |
| 12053 ' Special writable attribute: "tb_next" is the next level in ' | |
| 12054 'the\n' | |
| 12055 ' stack trace (towards the frame where the exception occurred), ' | |
| 12056 'or\n' | |
| 12057 ' "None" if there is no next level.\n' | |
| 12058 '\n' | |
| 12059 ' Changed in version 3.7: Traceback objects can now be ' | |
| 12060 'explicitly\n' | |
| 12061 ' instantiated from Python code, and the "tb_next" attribute ' | |
| 12062 'of\n' | |
| 12063 ' existing instances can be updated.\n' | |
| 12064 '\n' | |
| 12065 ' Slice objects\n' | |
| 12066 ' Slice objects are used to represent slices for ' | |
| 12067 '"__getitem__()"\n' | |
| 12068 ' methods. They are also created by the built-in "slice()"\n' | |
| 12069 ' function.\n' | |
| 12070 '\n' | |
| 12071 ' Special read-only attributes: "start" is the lower bound; ' | |
| 12072 '"stop"\n' | |
| 12073 ' is the upper bound; "step" is the step value; each is "None" ' | |
| 12074 'if\n' | |
| 12075 ' omitted. These attributes can have any type.\n' | |
| 12076 '\n' | |
| 12077 ' Slice objects support one method:\n' | |
| 12078 '\n' | |
| 12079 ' slice.indices(self, length)\n' | |
| 12080 '\n' | |
| 12081 ' This method takes a single integer argument *length* and\n' | |
| 12082 ' computes information about the slice that the slice ' | |
| 12083 'object\n' | |
| 12084 ' would describe if applied to a sequence of *length* ' | |
| 12085 'items.\n' | |
| 12086 ' It returns a tuple of three integers; respectively these ' | |
| 12087 'are\n' | |
| 12088 ' the *start* and *stop* indices and the *step* or stride\n' | |
| 12089 ' length of the slice. Missing or out-of-bounds indices are\n' | |
| 12090 ' handled in a manner consistent with regular slices.\n' | |
| 12091 '\n' | |
| 12092 ' Static method objects\n' | |
| 12093 ' Static method objects provide a way of defeating the\n' | |
| 12094 ' transformation of function objects to method objects ' | |
| 12095 'described\n' | |
| 12096 ' above. A static method object is a wrapper around any other\n' | |
| 12097 ' object, usually a user-defined method object. When a static\n' | |
| 12098 ' method object is retrieved from a class or a class instance, ' | |
| 12099 'the\n' | |
| 12100 ' object actually returned is the wrapped object, which is not\n' | |
| 12101 ' subject to any further transformation. Static method objects ' | |
| 12102 'are\n' | |
| 12103 ' not themselves callable, although the objects they wrap ' | |
| 12104 'usually\n' | |
| 12105 ' are. Static method objects are created by the built-in\n' | |
| 12106 ' "staticmethod()" constructor.\n' | |
| 12107 '\n' | |
| 12108 ' Class method objects\n' | |
| 12109 ' A class method object, like a static method object, is a ' | |
| 12110 'wrapper\n' | |
| 12111 ' around another object that alters the way in which that ' | |
| 12112 'object\n' | |
| 12113 ' is retrieved from classes and class instances. The behaviour ' | |
| 12114 'of\n' | |
| 12115 ' class method objects upon such retrieval is described above,\n' | |
| 12116 ' under “User-defined methods”. Class method objects are ' | |
| 12117 'created\n' | |
| 12118 ' by the built-in "classmethod()" constructor.\n', | |
| 12119 'typesfunctions': 'Functions\n' | |
| 12120 '*********\n' | |
| 12121 '\n' | |
| 12122 'Function objects are created by function definitions. The ' | |
| 12123 'only\n' | |
| 12124 'operation on a function object is to call it: ' | |
| 12125 '"func(argument-list)".\n' | |
| 12126 '\n' | |
| 12127 'There are really two flavors of function objects: built-in ' | |
| 12128 'functions\n' | |
| 12129 'and user-defined functions. Both support the same ' | |
| 12130 'operation (to call\n' | |
| 12131 'the function), but the implementation is different, hence ' | |
| 12132 'the\n' | |
| 12133 'different object types.\n' | |
| 12134 '\n' | |
| 12135 'See Function definitions for more information.\n', | |
| 12136 'typesmapping': 'Mapping Types — "dict"\n' | |
| 12137 '**********************\n' | |
| 12138 '\n' | |
| 12139 'A *mapping* object maps *hashable* values to arbitrary ' | |
| 12140 'objects.\n' | |
| 12141 'Mappings are mutable objects. There is currently only one ' | |
| 12142 'standard\n' | |
| 12143 'mapping type, the *dictionary*. (For other containers see ' | |
| 12144 'the built-\n' | |
| 12145 'in "list", "set", and "tuple" classes, and the "collections" ' | |
| 12146 'module.)\n' | |
| 12147 '\n' | |
| 12148 'A dictionary’s keys are *almost* arbitrary values. Values ' | |
| 12149 'that are\n' | |
| 12150 'not *hashable*, that is, values containing lists, ' | |
| 12151 'dictionaries or\n' | |
| 12152 'other mutable types (that are compared by value rather than ' | |
| 12153 'by object\n' | |
| 12154 'identity) may not be used as keys. Numeric types used for ' | |
| 12155 'keys obey\n' | |
| 12156 'the normal rules for numeric comparison: if two numbers ' | |
| 12157 'compare equal\n' | |
| 12158 '(such as "1" and "1.0") then they can be used ' | |
| 12159 'interchangeably to index\n' | |
| 12160 'the same dictionary entry. (Note however, that since ' | |
| 12161 'computers store\n' | |
| 12162 'floating-point numbers as approximations it is usually ' | |
| 12163 'unwise to use\n' | |
| 12164 'them as dictionary keys.)\n' | |
| 12165 '\n' | |
| 12166 'Dictionaries can be created by placing a comma-separated ' | |
| 12167 'list of "key:\n' | |
| 12168 'value" pairs within braces, for example: "{\'jack\': 4098, ' | |
| 12169 "'sjoerd':\n" | |
| 12170 '4127}" or "{4098: \'jack\', 4127: \'sjoerd\'}", or by the ' | |
| 12171 '"dict"\n' | |
| 12172 'constructor.\n' | |
| 12173 '\n' | |
| 12174 'class dict(**kwarg)\n' | |
| 12175 'class dict(mapping, **kwarg)\n' | |
| 12176 'class dict(iterable, **kwarg)\n' | |
| 12177 '\n' | |
| 12178 ' Return a new dictionary initialized from an optional ' | |
| 12179 'positional\n' | |
| 12180 ' argument and a possibly empty set of keyword arguments.\n' | |
| 12181 '\n' | |
| 12182 ' If no positional argument is given, an empty dictionary ' | |
| 12183 'is created.\n' | |
| 12184 ' If a positional argument is given and it is a mapping ' | |
| 12185 'object, a\n' | |
| 12186 ' dictionary is created with the same key-value pairs as ' | |
| 12187 'the mapping\n' | |
| 12188 ' object. Otherwise, the positional argument must be an ' | |
| 12189 '*iterable*\n' | |
| 12190 ' object. Each item in the iterable must itself be an ' | |
| 12191 'iterable with\n' | |
| 12192 ' exactly two objects. The first object of each item ' | |
| 12193 'becomes a key\n' | |
| 12194 ' in the new dictionary, and the second object the ' | |
| 12195 'corresponding\n' | |
| 12196 ' value. If a key occurs more than once, the last value ' | |
| 12197 'for that key\n' | |
| 12198 ' becomes the corresponding value in the new dictionary.\n' | |
| 12199 '\n' | |
| 12200 ' If keyword arguments are given, the keyword arguments and ' | |
| 12201 'their\n' | |
| 12202 ' values are added to the dictionary created from the ' | |
| 12203 'positional\n' | |
| 12204 ' argument. If a key being added is already present, the ' | |
| 12205 'value from\n' | |
| 12206 ' the keyword argument replaces the value from the ' | |
| 12207 'positional\n' | |
| 12208 ' argument.\n' | |
| 12209 '\n' | |
| 12210 ' To illustrate, the following examples all return a ' | |
| 12211 'dictionary equal\n' | |
| 12212 ' to "{"one": 1, "two": 2, "three": 3}":\n' | |
| 12213 '\n' | |
| 12214 ' >>> a = dict(one=1, two=2, three=3)\n' | |
| 12215 " >>> b = {'one': 1, 'two': 2, 'three': 3}\n" | |
| 12216 " >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))\n" | |
| 12217 " >>> d = dict([('two', 2), ('one', 1), ('three', 3)])\n" | |
| 12218 " >>> e = dict({'three': 3, 'one': 1, 'two': 2})\n" | |
| 12219 ' >>> a == b == c == d == e\n' | |
| 12220 ' True\n' | |
| 12221 '\n' | |
| 12222 ' Providing keyword arguments as in the first example only ' | |
| 12223 'works for\n' | |
| 12224 ' keys that are valid Python identifiers. Otherwise, any ' | |
| 12225 'valid keys\n' | |
| 12226 ' can be used.\n' | |
| 12227 '\n' | |
| 12228 ' These are the operations that dictionaries support (and ' | |
| 12229 'therefore,\n' | |
| 12230 ' custom mapping types should support too):\n' | |
| 12231 '\n' | |
| 12232 ' list(d)\n' | |
| 12233 '\n' | |
| 12234 ' Return a list of all the keys used in the dictionary ' | |
| 12235 '*d*.\n' | |
| 12236 '\n' | |
| 12237 ' len(d)\n' | |
| 12238 '\n' | |
| 12239 ' Return the number of items in the dictionary *d*.\n' | |
| 12240 '\n' | |
| 12241 ' d[key]\n' | |
| 12242 '\n' | |
| 12243 ' Return the item of *d* with key *key*. Raises a ' | |
| 12244 '"KeyError" if\n' | |
| 12245 ' *key* is not in the map.\n' | |
| 12246 '\n' | |
| 12247 ' If a subclass of dict defines a method "__missing__()" ' | |
| 12248 'and *key*\n' | |
| 12249 ' is not present, the "d[key]" operation calls that ' | |
| 12250 'method with\n' | |
| 12251 ' the key *key* as argument. The "d[key]" operation ' | |
| 12252 'then returns\n' | |
| 12253 ' or raises whatever is returned or raised by the\n' | |
| 12254 ' "__missing__(key)" call. No other operations or ' | |
| 12255 'methods invoke\n' | |
| 12256 ' "__missing__()". If "__missing__()" is not defined, ' | |
| 12257 '"KeyError"\n' | |
| 12258 ' is raised. "__missing__()" must be a method; it cannot ' | |
| 12259 'be an\n' | |
| 12260 ' instance variable:\n' | |
| 12261 '\n' | |
| 12262 ' >>> class Counter(dict):\n' | |
| 12263 ' ... def __missing__(self, key):\n' | |
| 12264 ' ... return 0\n' | |
| 12265 ' >>> c = Counter()\n' | |
| 12266 " >>> c['red']\n" | |
| 12267 ' 0\n' | |
| 12268 " >>> c['red'] += 1\n" | |
| 12269 " >>> c['red']\n" | |
| 12270 ' 1\n' | |
| 12271 '\n' | |
| 12272 ' The example above shows part of the implementation of\n' | |
| 12273 ' "collections.Counter". A different "__missing__" ' | |
| 12274 'method is used\n' | |
| 12275 ' by "collections.defaultdict".\n' | |
| 12276 '\n' | |
| 12277 ' d[key] = value\n' | |
| 12278 '\n' | |
| 12279 ' Set "d[key]" to *value*.\n' | |
| 12280 '\n' | |
| 12281 ' del d[key]\n' | |
| 12282 '\n' | |
| 12283 ' Remove "d[key]" from *d*. Raises a "KeyError" if ' | |
| 12284 '*key* is not\n' | |
| 12285 ' in the map.\n' | |
| 12286 '\n' | |
| 12287 ' key in d\n' | |
| 12288 '\n' | |
| 12289 ' Return "True" if *d* has a key *key*, else "False".\n' | |
| 12290 '\n' | |
| 12291 ' key not in d\n' | |
| 12292 '\n' | |
| 12293 ' Equivalent to "not key in d".\n' | |
| 12294 '\n' | |
| 12295 ' iter(d)\n' | |
| 12296 '\n' | |
| 12297 ' Return an iterator over the keys of the dictionary. ' | |
| 12298 'This is a\n' | |
| 12299 ' shortcut for "iter(d.keys())".\n' | |
| 12300 '\n' | |
| 12301 ' clear()\n' | |
| 12302 '\n' | |
| 12303 ' Remove all items from the dictionary.\n' | |
| 12304 '\n' | |
| 12305 ' copy()\n' | |
| 12306 '\n' | |
| 12307 ' Return a shallow copy of the dictionary.\n' | |
| 12308 '\n' | |
| 12309 ' classmethod fromkeys(iterable[, value])\n' | |
| 12310 '\n' | |
| 12311 ' Create a new dictionary with keys from *iterable* and ' | |
| 12312 'values set\n' | |
| 12313 ' to *value*.\n' | |
| 12314 '\n' | |
| 12315 ' "fromkeys()" is a class method that returns a new ' | |
| 12316 'dictionary.\n' | |
| 12317 ' *value* defaults to "None". All of the values refer ' | |
| 12318 'to just a\n' | |
| 12319 ' single instance, so it generally doesn’t make sense ' | |
| 12320 'for *value*\n' | |
| 12321 ' to be a mutable object such as an empty list. To get ' | |
| 12322 'distinct\n' | |
| 12323 ' values, use a dict comprehension instead.\n' | |
| 12324 '\n' | |
| 12325 ' get(key[, default])\n' | |
| 12326 '\n' | |
| 12327 ' Return the value for *key* if *key* is in the ' | |
| 12328 'dictionary, else\n' | |
| 12329 ' *default*. If *default* is not given, it defaults to ' | |
| 12330 '"None", so\n' | |
| 12331 ' that this method never raises a "KeyError".\n' | |
| 12332 '\n' | |
| 12333 ' items()\n' | |
| 12334 '\n' | |
| 12335 ' Return a new view of the dictionary’s items ("(key, ' | |
| 12336 'value)"\n' | |
| 12337 ' pairs). See the documentation of view objects.\n' | |
| 12338 '\n' | |
| 12339 ' keys()\n' | |
| 12340 '\n' | |
| 12341 ' Return a new view of the dictionary’s keys. See the\n' | |
| 12342 ' documentation of view objects.\n' | |
| 12343 '\n' | |
| 12344 ' pop(key[, default])\n' | |
| 12345 '\n' | |
| 12346 ' If *key* is in the dictionary, remove it and return ' | |
| 12347 'its value,\n' | |
| 12348 ' else return *default*. If *default* is not given and ' | |
| 12349 '*key* is\n' | |
| 12350 ' not in the dictionary, a "KeyError" is raised.\n' | |
| 12351 '\n' | |
| 12352 ' popitem()\n' | |
| 12353 '\n' | |
| 12354 ' Remove and return a "(key, value)" pair from the ' | |
| 12355 'dictionary.\n' | |
| 12356 ' Pairs are returned in LIFO (last-in, first-out) ' | |
| 12357 'order.\n' | |
| 12358 '\n' | |
| 12359 ' "popitem()" is useful to destructively iterate over a\n' | |
| 12360 ' dictionary, as often used in set algorithms. If the ' | |
| 12361 'dictionary\n' | |
| 12362 ' is empty, calling "popitem()" raises a "KeyError".\n' | |
| 12363 '\n' | |
| 12364 ' Changed in version 3.7: LIFO order is now guaranteed. ' | |
| 12365 'In prior\n' | |
| 12366 ' versions, "popitem()" would return an arbitrary ' | |
| 12367 'key/value pair.\n' | |
| 12368 '\n' | |
| 12369 ' reversed(d)\n' | |
| 12370 '\n' | |
| 12371 ' Return a reverse iterator over the keys of the ' | |
| 12372 'dictionary. This\n' | |
| 12373 ' is a shortcut for "reversed(d.keys())".\n' | |
| 12374 '\n' | |
| 12375 ' setdefault(key[, default])\n' | |
| 12376 '\n' | |
| 12377 ' If *key* is in the dictionary, return its value. If ' | |
| 12378 'not, insert\n' | |
| 12379 ' *key* with a value of *default* and return *default*. ' | |
| 12380 '*default*\n' | |
| 12381 ' defaults to "None".\n' | |
| 12382 '\n' | |
| 12383 ' update([other])\n' | |
| 12384 '\n' | |
| 12385 ' Update the dictionary with the key/value pairs from ' | |
| 12386 '*other*,\n' | |
| 12387 ' overwriting existing keys. Return "None".\n' | |
| 12388 '\n' | |
| 12389 ' "update()" accepts either another dictionary object or ' | |
| 12390 'an\n' | |
| 12391 ' iterable of key/value pairs (as tuples or other ' | |
| 12392 'iterables of\n' | |
| 12393 ' length two). If keyword arguments are specified, the ' | |
| 12394 'dictionary\n' | |
| 12395 ' is then updated with those key/value pairs: ' | |
| 12396 '"d.update(red=1,\n' | |
| 12397 ' blue=2)".\n' | |
| 12398 '\n' | |
| 12399 ' values()\n' | |
| 12400 '\n' | |
| 12401 ' Return a new view of the dictionary’s values. See ' | |
| 12402 'the\n' | |
| 12403 ' documentation of view objects.\n' | |
| 12404 '\n' | |
| 12405 ' An equality comparison between one "dict.values()" ' | |
| 12406 'view and\n' | |
| 12407 ' another will always return "False". This also applies ' | |
| 12408 'when\n' | |
| 12409 ' comparing "dict.values()" to itself:\n' | |
| 12410 '\n' | |
| 12411 " >>> d = {'a': 1}\n" | |
| 12412 ' >>> d.values() == d.values()\n' | |
| 12413 ' False\n' | |
| 12414 '\n' | |
| 12415 ' Dictionaries compare equal if and only if they have the ' | |
| 12416 'same "(key,\n' | |
| 12417 ' value)" pairs (regardless of ordering). Order comparisons ' | |
| 12418 '(‘<’,\n' | |
| 12419 ' ‘<=’, ‘>=’, ‘>’) raise "TypeError".\n' | |
| 12420 '\n' | |
| 12421 ' Dictionaries preserve insertion order. Note that ' | |
| 12422 'updating a key\n' | |
| 12423 ' does not affect the order. Keys added after deletion are ' | |
| 12424 'inserted\n' | |
| 12425 ' at the end.\n' | |
| 12426 '\n' | |
| 12427 ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' | |
| 12428 ' >>> d\n' | |
| 12429 " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" | |
| 12430 ' >>> list(d)\n' | |
| 12431 " ['one', 'two', 'three', 'four']\n" | |
| 12432 ' >>> list(d.values())\n' | |
| 12433 ' [1, 2, 3, 4]\n' | |
| 12434 ' >>> d["one"] = 42\n' | |
| 12435 ' >>> d\n' | |
| 12436 " {'one': 42, 'two': 2, 'three': 3, 'four': 4}\n" | |
| 12437 ' >>> del d["two"]\n' | |
| 12438 ' >>> d["two"] = None\n' | |
| 12439 ' >>> d\n' | |
| 12440 " {'one': 42, 'three': 3, 'four': 4, 'two': None}\n" | |
| 12441 '\n' | |
| 12442 ' Changed in version 3.7: Dictionary order is guaranteed to ' | |
| 12443 'be\n' | |
| 12444 ' insertion order. This behavior was an implementation ' | |
| 12445 'detail of\n' | |
| 12446 ' CPython from 3.6.\n' | |
| 12447 '\n' | |
| 12448 ' Dictionaries and dictionary views are reversible.\n' | |
| 12449 '\n' | |
| 12450 ' >>> d = {"one": 1, "two": 2, "three": 3, "four": 4}\n' | |
| 12451 ' >>> d\n' | |
| 12452 " {'one': 1, 'two': 2, 'three': 3, 'four': 4}\n" | |
| 12453 ' >>> list(reversed(d))\n' | |
| 12454 " ['four', 'three', 'two', 'one']\n" | |
| 12455 ' >>> list(reversed(d.values()))\n' | |
| 12456 ' [4, 3, 2, 1]\n' | |
| 12457 ' >>> list(reversed(d.items()))\n' | |
| 12458 " [('four', 4), ('three', 3), ('two', 2), ('one', 1)]\n" | |
| 12459 '\n' | |
| 12460 ' Changed in version 3.8: Dictionaries are now reversible.\n' | |
| 12461 '\n' | |
| 12462 'See also: "types.MappingProxyType" can be used to create a ' | |
| 12463 'read-only\n' | |
| 12464 ' view of a "dict".\n' | |
| 12465 '\n' | |
| 12466 '\n' | |
| 12467 'Dictionary view objects\n' | |
| 12468 '=======================\n' | |
| 12469 '\n' | |
| 12470 'The objects returned by "dict.keys()", "dict.values()" and\n' | |
| 12471 '"dict.items()" are *view objects*. They provide a dynamic ' | |
| 12472 'view on the\n' | |
| 12473 'dictionary’s entries, which means that when the dictionary ' | |
| 12474 'changes,\n' | |
| 12475 'the view reflects these changes.\n' | |
| 12476 '\n' | |
| 12477 'Dictionary views can be iterated over to yield their ' | |
| 12478 'respective data,\n' | |
| 12479 'and support membership tests:\n' | |
| 12480 '\n' | |
| 12481 'len(dictview)\n' | |
| 12482 '\n' | |
| 12483 ' Return the number of entries in the dictionary.\n' | |
| 12484 '\n' | |
| 12485 'iter(dictview)\n' | |
| 12486 '\n' | |
| 12487 ' Return an iterator over the keys, values or items ' | |
| 12488 '(represented as\n' | |
| 12489 ' tuples of "(key, value)") in the dictionary.\n' | |
| 12490 '\n' | |
| 12491 ' Keys and values are iterated over in insertion order. ' | |
| 12492 'This allows\n' | |
| 12493 ' the creation of "(value, key)" pairs using "zip()": ' | |
| 12494 '"pairs =\n' | |
| 12495 ' zip(d.values(), d.keys())". Another way to create the ' | |
| 12496 'same list is\n' | |
| 12497 ' "pairs = [(v, k) for (k, v) in d.items()]".\n' | |
| 12498 '\n' | |
| 12499 ' Iterating views while adding or deleting entries in the ' | |
| 12500 'dictionary\n' | |
| 12501 ' may raise a "RuntimeError" or fail to iterate over all ' | |
| 12502 'entries.\n' | |
| 12503 '\n' | |
| 12504 ' Changed in version 3.7: Dictionary order is guaranteed to ' | |
| 12505 'be\n' | |
| 12506 ' insertion order.\n' | |
| 12507 '\n' | |
| 12508 'x in dictview\n' | |
| 12509 '\n' | |
| 12510 ' Return "True" if *x* is in the underlying dictionary’s ' | |
| 12511 'keys, values\n' | |
| 12512 ' or items (in the latter case, *x* should be a "(key, ' | |
| 12513 'value)"\n' | |
| 12514 ' tuple).\n' | |
| 12515 '\n' | |
| 12516 'reversed(dictview)\n' | |
| 12517 '\n' | |
| 12518 ' Return a reverse iterator over the keys, values or items ' | |
| 12519 'of the\n' | |
| 12520 ' dictionary. The view will be iterated in reverse order of ' | |
| 12521 'the\n' | |
| 12522 ' insertion.\n' | |
| 12523 '\n' | |
| 12524 ' Changed in version 3.8: Dictionary views are now ' | |
| 12525 'reversible.\n' | |
| 12526 '\n' | |
| 12527 'Keys views are set-like since their entries are unique and ' | |
| 12528 'hashable.\n' | |
| 12529 'If all values are hashable, so that "(key, value)" pairs are ' | |
| 12530 'unique\n' | |
| 12531 'and hashable, then the items view is also set-like. (Values ' | |
| 12532 'views are\n' | |
| 12533 'not treated as set-like since the entries are generally not ' | |
| 12534 'unique.)\n' | |
| 12535 'For set-like views, all of the operations defined for the ' | |
| 12536 'abstract\n' | |
| 12537 'base class "collections.abc.Set" are available (for example, ' | |
| 12538 '"==",\n' | |
| 12539 '"<", or "^").\n' | |
| 12540 '\n' | |
| 12541 'An example of dictionary view usage:\n' | |
| 12542 '\n' | |
| 12543 " >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, " | |
| 12544 "'spam': 500}\n" | |
| 12545 ' >>> keys = dishes.keys()\n' | |
| 12546 ' >>> values = dishes.values()\n' | |
| 12547 '\n' | |
| 12548 ' >>> # iteration\n' | |
| 12549 ' >>> n = 0\n' | |
| 12550 ' >>> for val in values:\n' | |
| 12551 ' ... n += val\n' | |
| 12552 ' >>> print(n)\n' | |
| 12553 ' 504\n' | |
| 12554 '\n' | |
| 12555 ' >>> # keys and values are iterated over in the same order ' | |
| 12556 '(insertion order)\n' | |
| 12557 ' >>> list(keys)\n' | |
| 12558 " ['eggs', 'sausage', 'bacon', 'spam']\n" | |
| 12559 ' >>> list(values)\n' | |
| 12560 ' [2, 1, 1, 500]\n' | |
| 12561 '\n' | |
| 12562 ' >>> # view objects are dynamic and reflect dict changes\n' | |
| 12563 " >>> del dishes['eggs']\n" | |
| 12564 " >>> del dishes['sausage']\n" | |
| 12565 ' >>> list(keys)\n' | |
| 12566 " ['bacon', 'spam']\n" | |
| 12567 '\n' | |
| 12568 ' >>> # set operations\n' | |
| 12569 " >>> keys & {'eggs', 'bacon', 'salad'}\n" | |
| 12570 " {'bacon'}\n" | |
| 12571 " >>> keys ^ {'sausage', 'juice'}\n" | |
| 12572 " {'juice', 'sausage', 'bacon', 'spam'}\n", | |
| 12573 'typesmethods': 'Methods\n' | |
| 12574 '*******\n' | |
| 12575 '\n' | |
| 12576 'Methods are functions that are called using the attribute ' | |
| 12577 'notation.\n' | |
| 12578 'There are two flavors: built-in methods (such as "append()" ' | |
| 12579 'on lists)\n' | |
| 12580 'and class instance methods. Built-in methods are described ' | |
| 12581 'with the\n' | |
| 12582 'types that support them.\n' | |
| 12583 '\n' | |
| 12584 'If you access a method (a function defined in a class ' | |
| 12585 'namespace)\n' | |
| 12586 'through an instance, you get a special object: a *bound ' | |
| 12587 'method* (also\n' | |
| 12588 'called *instance method*) object. When called, it will add ' | |
| 12589 'the "self"\n' | |
| 12590 'argument to the argument list. Bound methods have two ' | |
| 12591 'special read-\n' | |
| 12592 'only attributes: "m.__self__" is the object on which the ' | |
| 12593 'method\n' | |
| 12594 'operates, and "m.__func__" is the function implementing the ' | |
| 12595 'method.\n' | |
| 12596 'Calling "m(arg-1, arg-2, ..., arg-n)" is completely ' | |
| 12597 'equivalent to\n' | |
| 12598 'calling "m.__func__(m.__self__, arg-1, arg-2, ..., arg-n)".\n' | |
| 12599 '\n' | |
| 12600 'Like function objects, bound method objects support getting ' | |
| 12601 'arbitrary\n' | |
| 12602 'attributes. However, since method attributes are actually ' | |
| 12603 'stored on\n' | |
| 12604 'the underlying function object ("meth.__func__"), setting ' | |
| 12605 'method\n' | |
| 12606 'attributes on bound methods is disallowed. Attempting to ' | |
| 12607 'set an\n' | |
| 12608 'attribute on a method results in an "AttributeError" being ' | |
| 12609 'raised. In\n' | |
| 12610 'order to set a method attribute, you need to explicitly set ' | |
| 12611 'it on the\n' | |
| 12612 'underlying function object:\n' | |
| 12613 '\n' | |
| 12614 ' >>> class C:\n' | |
| 12615 ' ... def method(self):\n' | |
| 12616 ' ... pass\n' | |
| 12617 ' ...\n' | |
| 12618 ' >>> c = C()\n' | |
| 12619 " >>> c.method.whoami = 'my name is method' # can't set on " | |
| 12620 'the method\n' | |
| 12621 ' Traceback (most recent call last):\n' | |
| 12622 ' File "<stdin>", line 1, in <module>\n' | |
| 12623 " AttributeError: 'method' object has no attribute " | |
| 12624 "'whoami'\n" | |
| 12625 " >>> c.method.__func__.whoami = 'my name is method'\n" | |
| 12626 ' >>> c.method.whoami\n' | |
| 12627 " 'my name is method'\n" | |
| 12628 '\n' | |
| 12629 'See The standard type hierarchy for more information.\n', | |
| 12630 'typesmodules': 'Modules\n' | |
| 12631 '*******\n' | |
| 12632 '\n' | |
| 12633 'The only special operation on a module is attribute access: ' | |
| 12634 '"m.name",\n' | |
| 12635 'where *m* is a module and *name* accesses a name defined in ' | |
| 12636 '*m*’s\n' | |
| 12637 'symbol table. Module attributes can be assigned to. (Note ' | |
| 12638 'that the\n' | |
| 12639 '"import" statement is not, strictly speaking, an operation ' | |
| 12640 'on a module\n' | |
| 12641 'object; "import foo" does not require a module object named ' | |
| 12642 '*foo* to\n' | |
| 12643 'exist, rather it requires an (external) *definition* for a ' | |
| 12644 'module\n' | |
| 12645 'named *foo* somewhere.)\n' | |
| 12646 '\n' | |
| 12647 'A special attribute of every module is "__dict__". This is ' | |
| 12648 'the\n' | |
| 12649 'dictionary containing the module’s symbol table. Modifying ' | |
| 12650 'this\n' | |
| 12651 'dictionary will actually change the module’s symbol table, ' | |
| 12652 'but direct\n' | |
| 12653 'assignment to the "__dict__" attribute is not possible (you ' | |
| 12654 'can write\n' | |
| 12655 '"m.__dict__[\'a\'] = 1", which defines "m.a" to be "1", but ' | |
| 12656 'you can’t\n' | |
| 12657 'write "m.__dict__ = {}"). Modifying "__dict__" directly is ' | |
| 12658 'not\n' | |
| 12659 'recommended.\n' | |
| 12660 '\n' | |
| 12661 'Modules built into the interpreter are written like this: ' | |
| 12662 '"<module\n' | |
| 12663 '\'sys\' (built-in)>". If loaded from a file, they are ' | |
| 12664 'written as\n' | |
| 12665 '"<module \'os\' from ' | |
| 12666 '\'/usr/local/lib/pythonX.Y/os.pyc\'>".\n', | |
| 12667 'typesseq': 'Sequence Types — "list", "tuple", "range"\n' | |
| 12668 '*****************************************\n' | |
| 12669 '\n' | |
| 12670 'There are three basic sequence types: lists, tuples, and range\n' | |
| 12671 'objects. Additional sequence types tailored for processing of ' | |
| 12672 'binary\n' | |
| 12673 'data and text strings are described in dedicated sections.\n' | |
| 12674 '\n' | |
| 12675 '\n' | |
| 12676 'Common Sequence Operations\n' | |
| 12677 '==========================\n' | |
| 12678 '\n' | |
| 12679 'The operations in the following table are supported by most ' | |
| 12680 'sequence\n' | |
| 12681 'types, both mutable and immutable. The ' | |
| 12682 '"collections.abc.Sequence" ABC\n' | |
| 12683 'is provided to make it easier to correctly implement these ' | |
| 12684 'operations\n' | |
| 12685 'on custom sequence types.\n' | |
| 12686 '\n' | |
| 12687 'This table lists the sequence operations sorted in ascending ' | |
| 12688 'priority.\n' | |
| 12689 'In the table, *s* and *t* are sequences of the same type, *n*, ' | |
| 12690 '*i*,\n' | |
| 12691 '*j* and *k* are integers and *x* is an arbitrary object that ' | |
| 12692 'meets any\n' | |
| 12693 'type and value restrictions imposed by *s*.\n' | |
| 12694 '\n' | |
| 12695 'The "in" and "not in" operations have the same priorities as ' | |
| 12696 'the\n' | |
| 12697 'comparison operations. The "+" (concatenation) and "*" ' | |
| 12698 '(repetition)\n' | |
| 12699 'operations have the same priority as the corresponding numeric\n' | |
| 12700 'operations. [3]\n' | |
| 12701 '\n' | |
| 12702 '+----------------------------+----------------------------------+------------+\n' | |
| 12703 '| Operation | Result ' | |
| 12704 '| Notes |\n' | |
| 12705 '|============================|==================================|============|\n' | |
| 12706 '| "x in s" | "True" if an item of *s* is ' | |
| 12707 '| (1) |\n' | |
| 12708 '| | equal to *x*, else "False" ' | |
| 12709 '| |\n' | |
| 12710 '+----------------------------+----------------------------------+------------+\n' | |
| 12711 '| "x not in s" | "False" if an item of *s* is ' | |
| 12712 '| (1) |\n' | |
| 12713 '| | equal to *x*, else "True" ' | |
| 12714 '| |\n' | |
| 12715 '+----------------------------+----------------------------------+------------+\n' | |
| 12716 '| "s + t" | the concatenation of *s* and *t* ' | |
| 12717 '| (6)(7) |\n' | |
| 12718 '+----------------------------+----------------------------------+------------+\n' | |
| 12719 '| "s * n" or "n * s" | equivalent to adding *s* to ' | |
| 12720 '| (2)(7) |\n' | |
| 12721 '| | itself *n* times ' | |
| 12722 '| |\n' | |
| 12723 '+----------------------------+----------------------------------+------------+\n' | |
| 12724 '| "s[i]" | *i*th item of *s*, origin 0 ' | |
| 12725 '| (3) |\n' | |
| 12726 '+----------------------------+----------------------------------+------------+\n' | |
| 12727 '| "s[i:j]" | slice of *s* from *i* to *j* ' | |
| 12728 '| (3)(4) |\n' | |
| 12729 '+----------------------------+----------------------------------+------------+\n' | |
| 12730 '| "s[i:j:k]" | slice of *s* from *i* to *j* ' | |
| 12731 '| (3)(5) |\n' | |
| 12732 '| | with step *k* ' | |
| 12733 '| |\n' | |
| 12734 '+----------------------------+----------------------------------+------------+\n' | |
| 12735 '| "len(s)" | length of *s* ' | |
| 12736 '| |\n' | |
| 12737 '+----------------------------+----------------------------------+------------+\n' | |
| 12738 '| "min(s)" | smallest item of *s* ' | |
| 12739 '| |\n' | |
| 12740 '+----------------------------+----------------------------------+------------+\n' | |
| 12741 '| "max(s)" | largest item of *s* ' | |
| 12742 '| |\n' | |
| 12743 '+----------------------------+----------------------------------+------------+\n' | |
| 12744 '| "s.index(x[, i[, j]])" | index of the first occurrence of ' | |
| 12745 '| (8) |\n' | |
| 12746 '| | *x* in *s* (at or after index ' | |
| 12747 '| |\n' | |
| 12748 '| | *i* and before index *j*) ' | |
| 12749 '| |\n' | |
| 12750 '+----------------------------+----------------------------------+------------+\n' | |
| 12751 '| "s.count(x)" | total number of occurrences of ' | |
| 12752 '| |\n' | |
| 12753 '| | *x* in *s* ' | |
| 12754 '| |\n' | |
| 12755 '+----------------------------+----------------------------------+------------+\n' | |
| 12756 '\n' | |
| 12757 'Sequences of the same type also support comparisons. In ' | |
| 12758 'particular,\n' | |
| 12759 'tuples and lists are compared lexicographically by comparing\n' | |
| 12760 'corresponding elements. This means that to compare equal, every\n' | |
| 12761 'element must compare equal and the two sequences must be of the ' | |
| 12762 'same\n' | |
| 12763 'type and have the same length. (For full details see ' | |
| 12764 'Comparisons in\n' | |
| 12765 'the language reference.)\n' | |
| 12766 '\n' | |
| 12767 'Notes:\n' | |
| 12768 '\n' | |
| 12769 '1. While the "in" and "not in" operations are used only for ' | |
| 12770 'simple\n' | |
| 12771 ' containment testing in the general case, some specialised ' | |
| 12772 'sequences\n' | |
| 12773 ' (such as "str", "bytes" and "bytearray") also use them for\n' | |
| 12774 ' subsequence testing:\n' | |
| 12775 '\n' | |
| 12776 ' >>> "gg" in "eggs"\n' | |
| 12777 ' True\n' | |
| 12778 '\n' | |
| 12779 '2. Values of *n* less than "0" are treated as "0" (which yields ' | |
| 12780 'an\n' | |
| 12781 ' empty sequence of the same type as *s*). Note that items in ' | |
| 12782 'the\n' | |
| 12783 ' sequence *s* are not copied; they are referenced multiple ' | |
| 12784 'times.\n' | |
| 12785 ' This often haunts new Python programmers; consider:\n' | |
| 12786 '\n' | |
| 12787 ' >>> lists = [[]] * 3\n' | |
| 12788 ' >>> lists\n' | |
| 12789 ' [[], [], []]\n' | |
| 12790 ' >>> lists[0].append(3)\n' | |
| 12791 ' >>> lists\n' | |
| 12792 ' [[3], [3], [3]]\n' | |
| 12793 '\n' | |
| 12794 ' What has happened is that "[[]]" is a one-element list ' | |
| 12795 'containing\n' | |
| 12796 ' an empty list, so all three elements of "[[]] * 3" are ' | |
| 12797 'references\n' | |
| 12798 ' to this single empty list. Modifying any of the elements of\n' | |
| 12799 ' "lists" modifies this single list. You can create a list of\n' | |
| 12800 ' different lists this way:\n' | |
| 12801 '\n' | |
| 12802 ' >>> lists = [[] for i in range(3)]\n' | |
| 12803 ' >>> lists[0].append(3)\n' | |
| 12804 ' >>> lists[1].append(5)\n' | |
| 12805 ' >>> lists[2].append(7)\n' | |
| 12806 ' >>> lists\n' | |
| 12807 ' [[3], [5], [7]]\n' | |
| 12808 '\n' | |
| 12809 ' Further explanation is available in the FAQ entry How do I ' | |
| 12810 'create a\n' | |
| 12811 ' multidimensional list?.\n' | |
| 12812 '\n' | |
| 12813 '3. If *i* or *j* is negative, the index is relative to the end ' | |
| 12814 'of\n' | |
| 12815 ' sequence *s*: "len(s) + i" or "len(s) + j" is substituted. ' | |
| 12816 'But\n' | |
| 12817 ' note that "-0" is still "0".\n' | |
| 12818 '\n' | |
| 12819 '4. The slice of *s* from *i* to *j* is defined as the sequence ' | |
| 12820 'of\n' | |
| 12821 ' items with index *k* such that "i <= k < j". If *i* or *j* ' | |
| 12822 'is\n' | |
| 12823 ' greater than "len(s)", use "len(s)". If *i* is omitted or ' | |
| 12824 '"None",\n' | |
| 12825 ' use "0". If *j* is omitted or "None", use "len(s)". If *i* ' | |
| 12826 'is\n' | |
| 12827 ' greater than or equal to *j*, the slice is empty.\n' | |
| 12828 '\n' | |
| 12829 '5. The slice of *s* from *i* to *j* with step *k* is defined as ' | |
| 12830 'the\n' | |
| 12831 ' sequence of items with index "x = i + n*k" such that "0 <= n ' | |
| 12832 '<\n' | |
| 12833 ' (j-i)/k". In other words, the indices are "i", "i+k", ' | |
| 12834 '"i+2*k",\n' | |
| 12835 ' "i+3*k" and so on, stopping when *j* is reached (but never\n' | |
| 12836 ' including *j*). When *k* is positive, *i* and *j* are ' | |
| 12837 'reduced to\n' | |
| 12838 ' "len(s)" if they are greater. When *k* is negative, *i* and ' | |
| 12839 '*j* are\n' | |
| 12840 ' reduced to "len(s) - 1" if they are greater. If *i* or *j* ' | |
| 12841 'are\n' | |
| 12842 ' omitted or "None", they become “end” values (which end ' | |
| 12843 'depends on\n' | |
| 12844 ' the sign of *k*). Note, *k* cannot be zero. If *k* is ' | |
| 12845 '"None", it\n' | |
| 12846 ' is treated like "1".\n' | |
| 12847 '\n' | |
| 12848 '6. Concatenating immutable sequences always results in a new\n' | |
| 12849 ' object. This means that building up a sequence by repeated\n' | |
| 12850 ' concatenation will have a quadratic runtime cost in the ' | |
| 12851 'total\n' | |
| 12852 ' sequence length. To get a linear runtime cost, you must ' | |
| 12853 'switch to\n' | |
| 12854 ' one of the alternatives below:\n' | |
| 12855 '\n' | |
| 12856 ' * if concatenating "str" objects, you can build a list and ' | |
| 12857 'use\n' | |
| 12858 ' "str.join()" at the end or else write to an "io.StringIO"\n' | |
| 12859 ' instance and retrieve its value when complete\n' | |
| 12860 '\n' | |
| 12861 ' * if concatenating "bytes" objects, you can similarly use\n' | |
| 12862 ' "bytes.join()" or "io.BytesIO", or you can do in-place\n' | |
| 12863 ' concatenation with a "bytearray" object. "bytearray" ' | |
| 12864 'objects are\n' | |
| 12865 ' mutable and have an efficient overallocation mechanism\n' | |
| 12866 '\n' | |
| 12867 ' * if concatenating "tuple" objects, extend a "list" instead\n' | |
| 12868 '\n' | |
| 12869 ' * for other types, investigate the relevant class ' | |
| 12870 'documentation\n' | |
| 12871 '\n' | |
| 12872 '7. Some sequence types (such as "range") only support item\n' | |
| 12873 ' sequences that follow specific patterns, and hence don’t ' | |
| 12874 'support\n' | |
| 12875 ' sequence concatenation or repetition.\n' | |
| 12876 '\n' | |
| 12877 '8. "index" raises "ValueError" when *x* is not found in *s*. ' | |
| 12878 'Not\n' | |
| 12879 ' all implementations support passing the additional arguments ' | |
| 12880 '*i*\n' | |
| 12881 ' and *j*. These arguments allow efficient searching of ' | |
| 12882 'subsections\n' | |
| 12883 ' of the sequence. Passing the extra arguments is roughly ' | |
| 12884 'equivalent\n' | |
| 12885 ' to using "s[i:j].index(x)", only without copying any data and ' | |
| 12886 'with\n' | |
| 12887 ' the returned index being relative to the start of the ' | |
| 12888 'sequence\n' | |
| 12889 ' rather than the start of the slice.\n' | |
| 12890 '\n' | |
| 12891 '\n' | |
| 12892 'Immutable Sequence Types\n' | |
| 12893 '========================\n' | |
| 12894 '\n' | |
| 12895 'The only operation that immutable sequence types generally ' | |
| 12896 'implement\n' | |
| 12897 'that is not also implemented by mutable sequence types is ' | |
| 12898 'support for\n' | |
| 12899 'the "hash()" built-in.\n' | |
| 12900 '\n' | |
| 12901 'This support allows immutable sequences, such as "tuple" ' | |
| 12902 'instances, to\n' | |
| 12903 'be used as "dict" keys and stored in "set" and "frozenset" ' | |
| 12904 'instances.\n' | |
| 12905 '\n' | |
| 12906 'Attempting to hash an immutable sequence that contains ' | |
| 12907 'unhashable\n' | |
| 12908 'values will result in "TypeError".\n' | |
| 12909 '\n' | |
| 12910 '\n' | |
| 12911 'Mutable Sequence Types\n' | |
| 12912 '======================\n' | |
| 12913 '\n' | |
| 12914 'The operations in the following table are defined on mutable ' | |
| 12915 'sequence\n' | |
| 12916 'types. The "collections.abc.MutableSequence" ABC is provided to ' | |
| 12917 'make\n' | |
| 12918 'it easier to correctly implement these operations on custom ' | |
| 12919 'sequence\n' | |
| 12920 'types.\n' | |
| 12921 '\n' | |
| 12922 'In the table *s* is an instance of a mutable sequence type, *t* ' | |
| 12923 'is any\n' | |
| 12924 'iterable object and *x* is an arbitrary object that meets any ' | |
| 12925 'type and\n' | |
| 12926 'value restrictions imposed by *s* (for example, "bytearray" ' | |
| 12927 'only\n' | |
| 12928 'accepts integers that meet the value restriction "0 <= x <= ' | |
| 12929 '255").\n' | |
| 12930 '\n' | |
| 12931 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12932 '| Operation | ' | |
| 12933 'Result | Notes |\n' | |
| 12934 '|================================|==================================|=======================|\n' | |
| 12935 '| "s[i] = x" | item *i* of *s* is replaced ' | |
| 12936 'by | |\n' | |
| 12937 '| | ' | |
| 12938 '*x* | |\n' | |
| 12939 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12940 '| "s[i:j] = t" | slice of *s* from *i* to *j* ' | |
| 12941 'is | |\n' | |
| 12942 '| | replaced by the contents of ' | |
| 12943 'the | |\n' | |
| 12944 '| | iterable ' | |
| 12945 '*t* | |\n' | |
| 12946 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12947 '| "del s[i:j]" | same as "s[i:j] = ' | |
| 12948 '[]" | |\n' | |
| 12949 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12950 '| "s[i:j:k] = t" | the elements of "s[i:j:k]" ' | |
| 12951 'are | (1) |\n' | |
| 12952 '| | replaced by those of ' | |
| 12953 '*t* | |\n' | |
| 12954 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12955 '| "del s[i:j:k]" | removes the elements ' | |
| 12956 'of | |\n' | |
| 12957 '| | "s[i:j:k]" from the ' | |
| 12958 'list | |\n' | |
| 12959 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12960 '| "s.append(x)" | appends *x* to the end of ' | |
| 12961 'the | |\n' | |
| 12962 '| | sequence (same ' | |
| 12963 'as | |\n' | |
| 12964 '| | "s[len(s):len(s)] = ' | |
| 12965 '[x]") | |\n' | |
| 12966 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12967 '| "s.clear()" | removes all items from *s* ' | |
| 12968 '(same | (5) |\n' | |
| 12969 '| | as "del ' | |
| 12970 's[:]") | |\n' | |
| 12971 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12972 '| "s.copy()" | creates a shallow copy of ' | |
| 12973 '*s* | (5) |\n' | |
| 12974 '| | (same as ' | |
| 12975 '"s[:]") | |\n' | |
| 12976 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12977 '| "s.extend(t)" or "s += t" | extends *s* with the contents ' | |
| 12978 'of | |\n' | |
| 12979 '| | *t* (for the most part the ' | |
| 12980 'same | |\n' | |
| 12981 '| | as "s[len(s):len(s)] = ' | |
| 12982 't") | |\n' | |
| 12983 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12984 '| "s *= n" | updates *s* with its ' | |
| 12985 'contents | (6) |\n' | |
| 12986 '| | repeated *n* ' | |
| 12987 'times | |\n' | |
| 12988 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12989 '| "s.insert(i, x)" | inserts *x* into *s* at ' | |
| 12990 'the | |\n' | |
| 12991 '| | index given by *i* (same ' | |
| 12992 'as | |\n' | |
| 12993 '| | "s[i:i] = ' | |
| 12994 '[x]") | |\n' | |
| 12995 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 12996 '| "s.pop([i])" | retrieves the item at *i* ' | |
| 12997 'and | (2) |\n' | |
| 12998 '| | also removes it from ' | |
| 12999 '*s* | |\n' | |
| 13000 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13001 '| "s.remove(x)" | remove the first item from ' | |
| 13002 '*s* | (3) |\n' | |
| 13003 '| | where "s[i]" is equal to ' | |
| 13004 '*x* | |\n' | |
| 13005 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13006 '| "s.reverse()" | reverses the items of *s* ' | |
| 13007 'in | (4) |\n' | |
| 13008 '| | ' | |
| 13009 'place | |\n' | |
| 13010 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13011 '\n' | |
| 13012 'Notes:\n' | |
| 13013 '\n' | |
| 13014 '1. *t* must have the same length as the slice it is replacing.\n' | |
| 13015 '\n' | |
| 13016 '2. The optional argument *i* defaults to "-1", so that by ' | |
| 13017 'default\n' | |
| 13018 ' the last item is removed and returned.\n' | |
| 13019 '\n' | |
| 13020 '3. "remove()" raises "ValueError" when *x* is not found in *s*.\n' | |
| 13021 '\n' | |
| 13022 '4. The "reverse()" method modifies the sequence in place for\n' | |
| 13023 ' economy of space when reversing a large sequence. To remind ' | |
| 13024 'users\n' | |
| 13025 ' that it operates by side effect, it does not return the ' | |
| 13026 'reversed\n' | |
| 13027 ' sequence.\n' | |
| 13028 '\n' | |
| 13029 '5. "clear()" and "copy()" are included for consistency with the\n' | |
| 13030 ' interfaces of mutable containers that don’t support slicing\n' | |
| 13031 ' operations (such as "dict" and "set"). "copy()" is not part ' | |
| 13032 'of the\n' | |
| 13033 ' "collections.abc.MutableSequence" ABC, but most concrete ' | |
| 13034 'mutable\n' | |
| 13035 ' sequence classes provide it.\n' | |
| 13036 '\n' | |
| 13037 ' New in version 3.3: "clear()" and "copy()" methods.\n' | |
| 13038 '\n' | |
| 13039 '6. The value *n* is an integer, or an object implementing\n' | |
| 13040 ' "__index__()". Zero and negative values of *n* clear the ' | |
| 13041 'sequence.\n' | |
| 13042 ' Items in the sequence are not copied; they are referenced ' | |
| 13043 'multiple\n' | |
| 13044 ' times, as explained for "s * n" under Common Sequence ' | |
| 13045 'Operations.\n' | |
| 13046 '\n' | |
| 13047 '\n' | |
| 13048 'Lists\n' | |
| 13049 '=====\n' | |
| 13050 '\n' | |
| 13051 'Lists are mutable sequences, typically used to store collections ' | |
| 13052 'of\n' | |
| 13053 'homogeneous items (where the precise degree of similarity will ' | |
| 13054 'vary by\n' | |
| 13055 'application).\n' | |
| 13056 '\n' | |
| 13057 'class list([iterable])\n' | |
| 13058 '\n' | |
| 13059 ' Lists may be constructed in several ways:\n' | |
| 13060 '\n' | |
| 13061 ' * Using a pair of square brackets to denote the empty list: ' | |
| 13062 '"[]"\n' | |
| 13063 '\n' | |
| 13064 ' * Using square brackets, separating items with commas: ' | |
| 13065 '"[a]",\n' | |
| 13066 ' "[a, b, c]"\n' | |
| 13067 '\n' | |
| 13068 ' * Using a list comprehension: "[x for x in iterable]"\n' | |
| 13069 '\n' | |
| 13070 ' * Using the type constructor: "list()" or "list(iterable)"\n' | |
| 13071 '\n' | |
| 13072 ' The constructor builds a list whose items are the same and in ' | |
| 13073 'the\n' | |
| 13074 ' same order as *iterable*’s items. *iterable* may be either ' | |
| 13075 'a\n' | |
| 13076 ' sequence, a container that supports iteration, or an ' | |
| 13077 'iterator\n' | |
| 13078 ' object. If *iterable* is already a list, a copy is made and\n' | |
| 13079 ' returned, similar to "iterable[:]". For example, ' | |
| 13080 '"list(\'abc\')"\n' | |
| 13081 ' returns "[\'a\', \'b\', \'c\']" and "list( (1, 2, 3) )" ' | |
| 13082 'returns "[1, 2,\n' | |
| 13083 ' 3]". If no argument is given, the constructor creates a new ' | |
| 13084 'empty\n' | |
| 13085 ' list, "[]".\n' | |
| 13086 '\n' | |
| 13087 ' Many other operations also produce lists, including the ' | |
| 13088 '"sorted()"\n' | |
| 13089 ' built-in.\n' | |
| 13090 '\n' | |
| 13091 ' Lists implement all of the common and mutable sequence ' | |
| 13092 'operations.\n' | |
| 13093 ' Lists also provide the following additional method:\n' | |
| 13094 '\n' | |
| 13095 ' sort(*, key=None, reverse=False)\n' | |
| 13096 '\n' | |
| 13097 ' This method sorts the list in place, using only "<" ' | |
| 13098 'comparisons\n' | |
| 13099 ' between items. Exceptions are not suppressed - if any ' | |
| 13100 'comparison\n' | |
| 13101 ' operations fail, the entire sort operation will fail (and ' | |
| 13102 'the\n' | |
| 13103 ' list will likely be left in a partially modified state).\n' | |
| 13104 '\n' | |
| 13105 ' "sort()" accepts two arguments that can only be passed by\n' | |
| 13106 ' keyword (keyword-only arguments):\n' | |
| 13107 '\n' | |
| 13108 ' *key* specifies a function of one argument that is used ' | |
| 13109 'to\n' | |
| 13110 ' extract a comparison key from each list element (for ' | |
| 13111 'example,\n' | |
| 13112 ' "key=str.lower"). The key corresponding to each item in ' | |
| 13113 'the list\n' | |
| 13114 ' is calculated once and then used for the entire sorting ' | |
| 13115 'process.\n' | |
| 13116 ' The default value of "None" means that list items are ' | |
| 13117 'sorted\n' | |
| 13118 ' directly without calculating a separate key value.\n' | |
| 13119 '\n' | |
| 13120 ' The "functools.cmp_to_key()" utility is available to ' | |
| 13121 'convert a\n' | |
| 13122 ' 2.x style *cmp* function to a *key* function.\n' | |
| 13123 '\n' | |
| 13124 ' *reverse* is a boolean value. If set to "True", then the ' | |
| 13125 'list\n' | |
| 13126 ' elements are sorted as if each comparison were reversed.\n' | |
| 13127 '\n' | |
| 13128 ' This method modifies the sequence in place for economy of ' | |
| 13129 'space\n' | |
| 13130 ' when sorting a large sequence. To remind users that it ' | |
| 13131 'operates\n' | |
| 13132 ' by side effect, it does not return the sorted sequence ' | |
| 13133 '(use\n' | |
| 13134 ' "sorted()" to explicitly request a new sorted list ' | |
| 13135 'instance).\n' | |
| 13136 '\n' | |
| 13137 ' The "sort()" method is guaranteed to be stable. A sort ' | |
| 13138 'is\n' | |
| 13139 ' stable if it guarantees not to change the relative order ' | |
| 13140 'of\n' | |
| 13141 ' elements that compare equal — this is helpful for sorting ' | |
| 13142 'in\n' | |
| 13143 ' multiple passes (for example, sort by department, then by ' | |
| 13144 'salary\n' | |
| 13145 ' grade).\n' | |
| 13146 '\n' | |
| 13147 ' For sorting examples and a brief sorting tutorial, see ' | |
| 13148 'Sorting\n' | |
| 13149 ' HOW TO.\n' | |
| 13150 '\n' | |
| 13151 ' **CPython implementation detail:** While a list is being ' | |
| 13152 'sorted,\n' | |
| 13153 ' the effect of attempting to mutate, or even inspect, the ' | |
| 13154 'list is\n' | |
| 13155 ' undefined. The C implementation of Python makes the list ' | |
| 13156 'appear\n' | |
| 13157 ' empty for the duration, and raises "ValueError" if it can ' | |
| 13158 'detect\n' | |
| 13159 ' that the list has been mutated during a sort.\n' | |
| 13160 '\n' | |
| 13161 '\n' | |
| 13162 'Tuples\n' | |
| 13163 '======\n' | |
| 13164 '\n' | |
| 13165 'Tuples are immutable sequences, typically used to store ' | |
| 13166 'collections of\n' | |
| 13167 'heterogeneous data (such as the 2-tuples produced by the ' | |
| 13168 '"enumerate()"\n' | |
| 13169 'built-in). Tuples are also used for cases where an immutable ' | |
| 13170 'sequence\n' | |
| 13171 'of homogeneous data is needed (such as allowing storage in a ' | |
| 13172 '"set" or\n' | |
| 13173 '"dict" instance).\n' | |
| 13174 '\n' | |
| 13175 'class tuple([iterable])\n' | |
| 13176 '\n' | |
| 13177 ' Tuples may be constructed in a number of ways:\n' | |
| 13178 '\n' | |
| 13179 ' * Using a pair of parentheses to denote the empty tuple: ' | |
| 13180 '"()"\n' | |
| 13181 '\n' | |
| 13182 ' * Using a trailing comma for a singleton tuple: "a," or ' | |
| 13183 '"(a,)"\n' | |
| 13184 '\n' | |
| 13185 ' * Separating items with commas: "a, b, c" or "(a, b, c)"\n' | |
| 13186 '\n' | |
| 13187 ' * Using the "tuple()" built-in: "tuple()" or ' | |
| 13188 '"tuple(iterable)"\n' | |
| 13189 '\n' | |
| 13190 ' The constructor builds a tuple whose items are the same and ' | |
| 13191 'in the\n' | |
| 13192 ' same order as *iterable*’s items. *iterable* may be either ' | |
| 13193 'a\n' | |
| 13194 ' sequence, a container that supports iteration, or an ' | |
| 13195 'iterator\n' | |
| 13196 ' object. If *iterable* is already a tuple, it is returned\n' | |
| 13197 ' unchanged. For example, "tuple(\'abc\')" returns "(\'a\', ' | |
| 13198 '\'b\', \'c\')"\n' | |
| 13199 ' and "tuple( [1, 2, 3] )" returns "(1, 2, 3)". If no argument ' | |
| 13200 'is\n' | |
| 13201 ' given, the constructor creates a new empty tuple, "()".\n' | |
| 13202 '\n' | |
| 13203 ' Note that it is actually the comma which makes a tuple, not ' | |
| 13204 'the\n' | |
| 13205 ' parentheses. The parentheses are optional, except in the ' | |
| 13206 'empty\n' | |
| 13207 ' tuple case, or when they are needed to avoid syntactic ' | |
| 13208 'ambiguity.\n' | |
| 13209 ' For example, "f(a, b, c)" is a function call with three ' | |
| 13210 'arguments,\n' | |
| 13211 ' while "f((a, b, c))" is a function call with a 3-tuple as the ' | |
| 13212 'sole\n' | |
| 13213 ' argument.\n' | |
| 13214 '\n' | |
| 13215 ' Tuples implement all of the common sequence operations.\n' | |
| 13216 '\n' | |
| 13217 'For heterogeneous collections of data where access by name is ' | |
| 13218 'clearer\n' | |
| 13219 'than access by index, "collections.namedtuple()" may be a more\n' | |
| 13220 'appropriate choice than a simple tuple object.\n' | |
| 13221 '\n' | |
| 13222 '\n' | |
| 13223 'Ranges\n' | |
| 13224 '======\n' | |
| 13225 '\n' | |
| 13226 'The "range" type represents an immutable sequence of numbers and ' | |
| 13227 'is\n' | |
| 13228 'commonly used for looping a specific number of times in "for" ' | |
| 13229 'loops.\n' | |
| 13230 '\n' | |
| 13231 'class range(stop)\n' | |
| 13232 'class range(start, stop[, step])\n' | |
| 13233 '\n' | |
| 13234 ' The arguments to the range constructor must be integers ' | |
| 13235 '(either\n' | |
| 13236 ' built-in "int" or any object that implements the "__index__"\n' | |
| 13237 ' special method). If the *step* argument is omitted, it ' | |
| 13238 'defaults to\n' | |
| 13239 ' "1". If the *start* argument is omitted, it defaults to "0". ' | |
| 13240 'If\n' | |
| 13241 ' *step* is zero, "ValueError" is raised.\n' | |
| 13242 '\n' | |
| 13243 ' For a positive *step*, the contents of a range "r" are ' | |
| 13244 'determined\n' | |
| 13245 ' by the formula "r[i] = start + step*i" where "i >= 0" and ' | |
| 13246 '"r[i] <\n' | |
| 13247 ' stop".\n' | |
| 13248 '\n' | |
| 13249 ' For a negative *step*, the contents of the range are still\n' | |
| 13250 ' determined by the formula "r[i] = start + step*i", but the\n' | |
| 13251 ' constraints are "i >= 0" and "r[i] > stop".\n' | |
| 13252 '\n' | |
| 13253 ' A range object will be empty if "r[0]" does not meet the ' | |
| 13254 'value\n' | |
| 13255 ' constraint. Ranges do support negative indices, but these ' | |
| 13256 'are\n' | |
| 13257 ' interpreted as indexing from the end of the sequence ' | |
| 13258 'determined by\n' | |
| 13259 ' the positive indices.\n' | |
| 13260 '\n' | |
| 13261 ' Ranges containing absolute values larger than "sys.maxsize" ' | |
| 13262 'are\n' | |
| 13263 ' permitted but some features (such as "len()") may raise\n' | |
| 13264 ' "OverflowError".\n' | |
| 13265 '\n' | |
| 13266 ' Range examples:\n' | |
| 13267 '\n' | |
| 13268 ' >>> list(range(10))\n' | |
| 13269 ' [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]\n' | |
| 13270 ' >>> list(range(1, 11))\n' | |
| 13271 ' [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n' | |
| 13272 ' >>> list(range(0, 30, 5))\n' | |
| 13273 ' [0, 5, 10, 15, 20, 25]\n' | |
| 13274 ' >>> list(range(0, 10, 3))\n' | |
| 13275 ' [0, 3, 6, 9]\n' | |
| 13276 ' >>> list(range(0, -10, -1))\n' | |
| 13277 ' [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]\n' | |
| 13278 ' >>> list(range(0))\n' | |
| 13279 ' []\n' | |
| 13280 ' >>> list(range(1, 0))\n' | |
| 13281 ' []\n' | |
| 13282 '\n' | |
| 13283 ' Ranges implement all of the common sequence operations ' | |
| 13284 'except\n' | |
| 13285 ' concatenation and repetition (due to the fact that range ' | |
| 13286 'objects\n' | |
| 13287 ' can only represent sequences that follow a strict pattern ' | |
| 13288 'and\n' | |
| 13289 ' repetition and concatenation will usually violate that ' | |
| 13290 'pattern).\n' | |
| 13291 '\n' | |
| 13292 ' start\n' | |
| 13293 '\n' | |
| 13294 ' The value of the *start* parameter (or "0" if the ' | |
| 13295 'parameter was\n' | |
| 13296 ' not supplied)\n' | |
| 13297 '\n' | |
| 13298 ' stop\n' | |
| 13299 '\n' | |
| 13300 ' The value of the *stop* parameter\n' | |
| 13301 '\n' | |
| 13302 ' step\n' | |
| 13303 '\n' | |
| 13304 ' The value of the *step* parameter (or "1" if the parameter ' | |
| 13305 'was\n' | |
| 13306 ' not supplied)\n' | |
| 13307 '\n' | |
| 13308 'The advantage of the "range" type over a regular "list" or ' | |
| 13309 '"tuple" is\n' | |
| 13310 'that a "range" object will always take the same (small) amount ' | |
| 13311 'of\n' | |
| 13312 'memory, no matter the size of the range it represents (as it ' | |
| 13313 'only\n' | |
| 13314 'stores the "start", "stop" and "step" values, calculating ' | |
| 13315 'individual\n' | |
| 13316 'items and subranges as needed).\n' | |
| 13317 '\n' | |
| 13318 'Range objects implement the "collections.abc.Sequence" ABC, and\n' | |
| 13319 'provide features such as containment tests, element index ' | |
| 13320 'lookup,\n' | |
| 13321 'slicing and support for negative indices (see Sequence Types — ' | |
| 13322 'list,\n' | |
| 13323 'tuple, range):\n' | |
| 13324 '\n' | |
| 13325 '>>> r = range(0, 20, 2)\n' | |
| 13326 '>>> r\n' | |
| 13327 'range(0, 20, 2)\n' | |
| 13328 '>>> 11 in r\n' | |
| 13329 'False\n' | |
| 13330 '>>> 10 in r\n' | |
| 13331 'True\n' | |
| 13332 '>>> r.index(10)\n' | |
| 13333 '5\n' | |
| 13334 '>>> r[5]\n' | |
| 13335 '10\n' | |
| 13336 '>>> r[:5]\n' | |
| 13337 'range(0, 10, 2)\n' | |
| 13338 '>>> r[-1]\n' | |
| 13339 '18\n' | |
| 13340 '\n' | |
| 13341 'Testing range objects for equality with "==" and "!=" compares ' | |
| 13342 'them as\n' | |
| 13343 'sequences. That is, two range objects are considered equal if ' | |
| 13344 'they\n' | |
| 13345 'represent the same sequence of values. (Note that two range ' | |
| 13346 'objects\n' | |
| 13347 'that compare equal might have different "start", "stop" and ' | |
| 13348 '"step"\n' | |
| 13349 'attributes, for example "range(0) == range(2, 1, 3)" or ' | |
| 13350 '"range(0, 3,\n' | |
| 13351 '2) == range(0, 4, 2)".)\n' | |
| 13352 '\n' | |
| 13353 'Changed in version 3.2: Implement the Sequence ABC. Support ' | |
| 13354 'slicing\n' | |
| 13355 'and negative indices. Test "int" objects for membership in ' | |
| 13356 'constant\n' | |
| 13357 'time instead of iterating through all items.\n' | |
| 13358 '\n' | |
| 13359 'Changed in version 3.3: Define ‘==’ and ‘!=’ to compare range ' | |
| 13360 'objects\n' | |
| 13361 'based on the sequence of values they define (instead of ' | |
| 13362 'comparing\n' | |
| 13363 'based on object identity).\n' | |
| 13364 '\n' | |
| 13365 'New in version 3.3: The "start", "stop" and "step" attributes.\n' | |
| 13366 '\n' | |
| 13367 'See also:\n' | |
| 13368 '\n' | |
| 13369 ' * The linspace recipe shows how to implement a lazy version ' | |
| 13370 'of\n' | |
| 13371 ' range suitable for floating point applications.\n', | |
| 13372 'typesseq-mutable': 'Mutable Sequence Types\n' | |
| 13373 '**********************\n' | |
| 13374 '\n' | |
| 13375 'The operations in the following table are defined on ' | |
| 13376 'mutable sequence\n' | |
| 13377 'types. The "collections.abc.MutableSequence" ABC is ' | |
| 13378 'provided to make\n' | |
| 13379 'it easier to correctly implement these operations on ' | |
| 13380 'custom sequence\n' | |
| 13381 'types.\n' | |
| 13382 '\n' | |
| 13383 'In the table *s* is an instance of a mutable sequence ' | |
| 13384 'type, *t* is any\n' | |
| 13385 'iterable object and *x* is an arbitrary object that ' | |
| 13386 'meets any type and\n' | |
| 13387 'value restrictions imposed by *s* (for example, ' | |
| 13388 '"bytearray" only\n' | |
| 13389 'accepts integers that meet the value restriction "0 <= x ' | |
| 13390 '<= 255").\n' | |
| 13391 '\n' | |
| 13392 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13393 '| Operation | ' | |
| 13394 'Result | Notes ' | |
| 13395 '|\n' | |
| 13396 '|================================|==================================|=======================|\n' | |
| 13397 '| "s[i] = x" | item *i* of *s* is ' | |
| 13398 'replaced by | |\n' | |
| 13399 '| | ' | |
| 13400 '*x* | ' | |
| 13401 '|\n' | |
| 13402 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13403 '| "s[i:j] = t" | slice of *s* from *i* ' | |
| 13404 'to *j* is | |\n' | |
| 13405 '| | replaced by the ' | |
| 13406 'contents of the | |\n' | |
| 13407 '| | iterable ' | |
| 13408 '*t* | |\n' | |
| 13409 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13410 '| "del s[i:j]" | same as "s[i:j] = ' | |
| 13411 '[]" | |\n' | |
| 13412 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13413 '| "s[i:j:k] = t" | the elements of ' | |
| 13414 '"s[i:j:k]" are | (1) |\n' | |
| 13415 '| | replaced by those of ' | |
| 13416 '*t* | |\n' | |
| 13417 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13418 '| "del s[i:j:k]" | removes the elements ' | |
| 13419 'of | |\n' | |
| 13420 '| | "s[i:j:k]" from the ' | |
| 13421 'list | |\n' | |
| 13422 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13423 '| "s.append(x)" | appends *x* to the ' | |
| 13424 'end of the | |\n' | |
| 13425 '| | sequence (same ' | |
| 13426 'as | |\n' | |
| 13427 '| | "s[len(s):len(s)] = ' | |
| 13428 '[x]") | |\n' | |
| 13429 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13430 '| "s.clear()" | removes all items ' | |
| 13431 'from *s* (same | (5) |\n' | |
| 13432 '| | as "del ' | |
| 13433 's[:]") | |\n' | |
| 13434 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13435 '| "s.copy()" | creates a shallow ' | |
| 13436 'copy of *s* | (5) |\n' | |
| 13437 '| | (same as ' | |
| 13438 '"s[:]") | |\n' | |
| 13439 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13440 '| "s.extend(t)" or "s += t" | extends *s* with the ' | |
| 13441 'contents of | |\n' | |
| 13442 '| | *t* (for the most ' | |
| 13443 'part the same | |\n' | |
| 13444 '| | as "s[len(s):len(s)] ' | |
| 13445 '= t") | |\n' | |
| 13446 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13447 '| "s *= n" | updates *s* with its ' | |
| 13448 'contents | (6) |\n' | |
| 13449 '| | repeated *n* ' | |
| 13450 'times | |\n' | |
| 13451 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13452 '| "s.insert(i, x)" | inserts *x* into *s* ' | |
| 13453 'at the | |\n' | |
| 13454 '| | index given by *i* ' | |
| 13455 '(same as | |\n' | |
| 13456 '| | "s[i:i] = ' | |
| 13457 '[x]") | |\n' | |
| 13458 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13459 '| "s.pop([i])" | retrieves the item at ' | |
| 13460 '*i* and | (2) |\n' | |
| 13461 '| | also removes it from ' | |
| 13462 '*s* | |\n' | |
| 13463 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13464 '| "s.remove(x)" | remove the first item ' | |
| 13465 'from *s* | (3) |\n' | |
| 13466 '| | where "s[i]" is equal ' | |
| 13467 'to *x* | |\n' | |
| 13468 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13469 '| "s.reverse()" | reverses the items of ' | |
| 13470 '*s* in | (4) |\n' | |
| 13471 '| | ' | |
| 13472 'place | ' | |
| 13473 '|\n' | |
| 13474 '+--------------------------------+----------------------------------+-----------------------+\n' | |
| 13475 '\n' | |
| 13476 'Notes:\n' | |
| 13477 '\n' | |
| 13478 '1. *t* must have the same length as the slice it is ' | |
| 13479 'replacing.\n' | |
| 13480 '\n' | |
| 13481 '2. The optional argument *i* defaults to "-1", so that ' | |
| 13482 'by default\n' | |
| 13483 ' the last item is removed and returned.\n' | |
| 13484 '\n' | |
| 13485 '3. "remove()" raises "ValueError" when *x* is not found ' | |
| 13486 'in *s*.\n' | |
| 13487 '\n' | |
| 13488 '4. The "reverse()" method modifies the sequence in place ' | |
| 13489 'for\n' | |
| 13490 ' economy of space when reversing a large sequence. To ' | |
| 13491 'remind users\n' | |
| 13492 ' that it operates by side effect, it does not return ' | |
| 13493 'the reversed\n' | |
| 13494 ' sequence.\n' | |
| 13495 '\n' | |
| 13496 '5. "clear()" and "copy()" are included for consistency ' | |
| 13497 'with the\n' | |
| 13498 ' interfaces of mutable containers that don’t support ' | |
| 13499 'slicing\n' | |
| 13500 ' operations (such as "dict" and "set"). "copy()" is ' | |
| 13501 'not part of the\n' | |
| 13502 ' "collections.abc.MutableSequence" ABC, but most ' | |
| 13503 'concrete mutable\n' | |
| 13504 ' sequence classes provide it.\n' | |
| 13505 '\n' | |
| 13506 ' New in version 3.3: "clear()" and "copy()" methods.\n' | |
| 13507 '\n' | |
| 13508 '6. The value *n* is an integer, or an object ' | |
| 13509 'implementing\n' | |
| 13510 ' "__index__()". Zero and negative values of *n* clear ' | |
| 13511 'the sequence.\n' | |
| 13512 ' Items in the sequence are not copied; they are ' | |
| 13513 'referenced multiple\n' | |
| 13514 ' times, as explained for "s * n" under Common Sequence ' | |
| 13515 'Operations.\n', | |
| 13516 'unary': 'Unary arithmetic and bitwise operations\n' | |
| 13517 '***************************************\n' | |
| 13518 '\n' | |
| 13519 'All unary arithmetic and bitwise operations have the same ' | |
| 13520 'priority:\n' | |
| 13521 '\n' | |
| 13522 ' u_expr ::= power | "-" u_expr | "+" u_expr | "~" u_expr\n' | |
| 13523 '\n' | |
| 13524 'The unary "-" (minus) operator yields the negation of its numeric\n' | |
| 13525 'argument.\n' | |
| 13526 '\n' | |
| 13527 'The unary "+" (plus) operator yields its numeric argument ' | |
| 13528 'unchanged.\n' | |
| 13529 '\n' | |
| 13530 'The unary "~" (invert) operator yields the bitwise inversion of ' | |
| 13531 'its\n' | |
| 13532 'integer argument. The bitwise inversion of "x" is defined as\n' | |
| 13533 '"-(x+1)". It only applies to integral numbers.\n' | |
| 13534 '\n' | |
| 13535 'In all three cases, if the argument does not have the proper type, ' | |
| 13536 'a\n' | |
| 13537 '"TypeError" exception is raised.\n', | |
| 13538 'while': 'The "while" statement\n' | |
| 13539 '*********************\n' | |
| 13540 '\n' | |
| 13541 'The "while" statement is used for repeated execution as long as an\n' | |
| 13542 'expression is true:\n' | |
| 13543 '\n' | |
| 13544 ' while_stmt ::= "while" expression ":" suite\n' | |
| 13545 ' ["else" ":" suite]\n' | |
| 13546 '\n' | |
| 13547 'This repeatedly tests the expression and, if it is true, executes ' | |
| 13548 'the\n' | |
| 13549 'first suite; if the expression is false (which may be the first ' | |
| 13550 'time\n' | |
| 13551 'it is tested) the suite of the "else" clause, if present, is ' | |
| 13552 'executed\n' | |
| 13553 'and the loop terminates.\n' | |
| 13554 '\n' | |
| 13555 'A "break" statement executed in the first suite terminates the ' | |
| 13556 'loop\n' | |
| 13557 'without executing the "else" clause’s suite. A "continue" ' | |
| 13558 'statement\n' | |
| 13559 'executed in the first suite skips the rest of the suite and goes ' | |
| 13560 'back\n' | |
| 13561 'to testing the expression.\n', | |
| 13562 'with': 'The "with" statement\n' | |
| 13563 '********************\n' | |
| 13564 '\n' | |
| 13565 'The "with" statement is used to wrap the execution of a block with\n' | |
| 13566 'methods defined by a context manager (see section With Statement\n' | |
| 13567 'Context Managers). This allows common "try"…"except"…"finally" ' | |
| 13568 'usage\n' | |
| 13569 'patterns to be encapsulated for convenient reuse.\n' | |
| 13570 '\n' | |
| 13571 ' with_stmt ::= "with" with_item ("," with_item)* ":" suite\n' | |
| 13572 ' with_item ::= expression ["as" target]\n' | |
| 13573 '\n' | |
| 13574 'The execution of the "with" statement with one “item” proceeds as\n' | |
| 13575 'follows:\n' | |
| 13576 '\n' | |
| 13577 '1. The context expression (the expression given in the "with_item")\n' | |
| 13578 ' is evaluated to obtain a context manager.\n' | |
| 13579 '\n' | |
| 13580 '2. The context manager’s "__exit__()" is loaded for later use.\n' | |
| 13581 '\n' | |
| 13582 '3. The context manager’s "__enter__()" method is invoked.\n' | |
| 13583 '\n' | |
| 13584 '4. If a target was included in the "with" statement, the return\n' | |
| 13585 ' value from "__enter__()" is assigned to it.\n' | |
| 13586 '\n' | |
| 13587 ' Note: The "with" statement guarantees that if the "__enter__()"\n' | |
| 13588 ' method returns without an error, then "__exit__()" will always ' | |
| 13589 'be\n' | |
| 13590 ' called. Thus, if an error occurs during the assignment to the\n' | |
| 13591 ' target list, it will be treated the same as an error occurring\n' | |
| 13592 ' within the suite would be. See step 6 below.\n' | |
| 13593 '\n' | |
| 13594 '5. The suite is executed.\n' | |
| 13595 '\n' | |
| 13596 '6. The context manager’s "__exit__()" method is invoked. If an\n' | |
| 13597 ' exception caused the suite to be exited, its type, value, and\n' | |
| 13598 ' traceback are passed as arguments to "__exit__()". Otherwise, ' | |
| 13599 'three\n' | |
| 13600 ' "None" arguments are supplied.\n' | |
| 13601 '\n' | |
| 13602 ' If the suite was exited due to an exception, and the return ' | |
| 13603 'value\n' | |
| 13604 ' from the "__exit__()" method was false, the exception is ' | |
| 13605 'reraised.\n' | |
| 13606 ' If the return value was true, the exception is suppressed, and\n' | |
| 13607 ' execution continues with the statement following the "with"\n' | |
| 13608 ' statement.\n' | |
| 13609 '\n' | |
| 13610 ' If the suite was exited for any reason other than an exception, ' | |
| 13611 'the\n' | |
| 13612 ' return value from "__exit__()" is ignored, and execution ' | |
| 13613 'proceeds\n' | |
| 13614 ' at the normal location for the kind of exit that was taken.\n' | |
| 13615 '\n' | |
| 13616 'With more than one item, the context managers are processed as if\n' | |
| 13617 'multiple "with" statements were nested:\n' | |
| 13618 '\n' | |
| 13619 ' with A() as a, B() as b:\n' | |
| 13620 ' suite\n' | |
| 13621 '\n' | |
| 13622 'is equivalent to\n' | |
| 13623 '\n' | |
| 13624 ' with A() as a:\n' | |
| 13625 ' with B() as b:\n' | |
| 13626 ' suite\n' | |
| 13627 '\n' | |
| 13628 'Changed in version 3.1: Support for multiple context expressions.\n' | |
| 13629 '\n' | |
| 13630 'See also:\n' | |
| 13631 '\n' | |
| 13632 ' **PEP 343** - The “with” statement\n' | |
| 13633 ' The specification, background, and examples for the Python ' | |
| 13634 '"with"\n' | |
| 13635 ' statement.\n', | |
| 13636 'yield': 'The "yield" statement\n' | |
| 13637 '*********************\n' | |
| 13638 '\n' | |
| 13639 ' yield_stmt ::= yield_expression\n' | |
| 13640 '\n' | |
| 13641 'A "yield" statement is semantically equivalent to a yield ' | |
| 13642 'expression.\n' | |
| 13643 'The yield statement can be used to omit the parentheses that would\n' | |
| 13644 'otherwise be required in the equivalent yield expression ' | |
| 13645 'statement.\n' | |
| 13646 'For example, the yield statements\n' | |
| 13647 '\n' | |
| 13648 ' yield <expr>\n' | |
| 13649 ' yield from <expr>\n' | |
| 13650 '\n' | |
| 13651 'are equivalent to the yield expression statements\n' | |
| 13652 '\n' | |
| 13653 ' (yield <expr>)\n' | |
| 13654 ' (yield from <expr>)\n' | |
| 13655 '\n' | |
| 13656 'Yield expressions and statements are only used when defining a\n' | |
| 13657 '*generator* function, and are only used in the body of the ' | |
| 13658 'generator\n' | |
| 13659 'function. Using yield in a function definition is sufficient to ' | |
| 13660 'cause\n' | |
| 13661 'that definition to create a generator function instead of a normal\n' | |
| 13662 'function.\n' | |
| 13663 '\n' | |
| 13664 'For full details of "yield" semantics, refer to the Yield ' | |
| 13665 'expressions\n' | |
| 13666 'section.\n'} |