/Doc/reference/datamodel.rst
ReStructuredText | 2439 lines | 1896 code | 543 blank | 0 comment | 0 complexity | 1a4a26c427249dcc208fc5f9df27b2b2 MD5 | raw file
Large files files are truncated, but you can click here to view the full file
1 2.. _datamodel: 3 4********** 5Data model 6********** 7 8 9.. _objects: 10 11Objects, values and types 12========================= 13 14.. index:: 15 single: object 16 single: data 17 18:dfn:`Objects` are Python's abstraction for data. All data in a Python program 19is represented by objects or by relations between objects. (In a sense, and in 20conformance to Von Neumann's model of a "stored program computer," code is also 21represented by objects.) 22 23.. index:: 24 builtin: id 25 builtin: type 26 single: identity of an object 27 single: value of an object 28 single: type of an object 29 single: mutable object 30 single: immutable object 31 32Every object has an identity, a type and a value. An object's *identity* never 33changes once it has been created; you may think of it as the object's address in 34memory. The ':keyword:`is`' operator compares the identity of two objects; the 35:func:`id` function returns an integer representing its identity (currently 36implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_ 37An object's type determines the operations that the object supports (e.g., "does 38it have a length?") and also defines the possible values for objects of that 39type. The :func:`type` function returns an object's type (which is an object 40itself). The *value* of some objects can change. Objects whose value can 41change are said to be *mutable*; objects whose value is unchangeable once they 42are created are called *immutable*. (The value of an immutable container object 43that contains a reference to a mutable object can change when the latter's value 44is changed; however the container is still considered immutable, because the 45collection of objects it contains cannot be changed. So, immutability is not 46strictly the same as having an unchangeable value, it is more subtle.) An 47object's mutability is determined by its type; for instance, numbers, strings 48and tuples are immutable, while dictionaries and lists are mutable. 49 50.. index:: 51 single: garbage collection 52 single: reference counting 53 single: unreachable object 54 55Objects are never explicitly destroyed; however, when they become unreachable 56they may be garbage-collected. An implementation is allowed to postpone garbage 57collection or omit it altogether --- it is a matter of implementation quality 58how garbage collection is implemented, as long as no objects are collected that 59are still reachable. (Implementation note: CPython currently uses a 60reference-counting scheme with (optional) delayed detection of cyclically linked 61garbage, which collects most objects as soon as they become unreachable, but is 62not guaranteed to collect garbage containing circular references. See the 63documentation of the :mod:`gc` module for information on controlling the 64collection of cyclic garbage. Other implementations act differently and CPython 65may change.) 66 67Note that the use of the implementation's tracing or debugging facilities may 68keep objects alive that would normally be collectable. Also note that catching 69an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep 70objects alive. 71 72Some objects contain references to "external" resources such as open files or 73windows. It is understood that these resources are freed when the object is 74garbage-collected, but since garbage collection is not guaranteed to happen, 75such objects also provide an explicit way to release the external resource, 76usually a :meth:`close` method. Programs are strongly recommended to explicitly 77close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement 78provides a convenient way to do this. 79 80.. index:: single: container 81 82Some objects contain references to other objects; these are called *containers*. 83Examples of containers are tuples, lists and dictionaries. The references are 84part of a container's value. In most cases, when we talk about the value of a 85container, we imply the values, not the identities of the contained objects; 86however, when we talk about the mutability of a container, only the identities 87of the immediately contained objects are implied. So, if an immutable container 88(like a tuple) contains a reference to a mutable object, its value changes if 89that mutable object is changed. 90 91Types affect almost all aspects of object behavior. Even the importance of 92object identity is affected in some sense: for immutable types, operations that 93compute new values may actually return a reference to any existing object with 94the same type and value, while for mutable objects this is not allowed. E.g., 95after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object 96with the value one, depending on the implementation, but after ``c = []; d = 97[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly 98created empty lists. (Note that ``c = d = []`` assigns the same object to both 99``c`` and ``d``.) 100 101 102.. _types: 103 104The standard type hierarchy 105=========================== 106 107.. index:: 108 single: type 109 pair: data; type 110 pair: type; hierarchy 111 pair: extension; module 112 pair: C; language 113 114Below is a list of the types that are built into Python. Extension modules 115(written in C, Java, or other languages, depending on the implementation) can 116define additional types. Future versions of Python may add types to the type 117hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.). 118 119.. index:: 120 single: attribute 121 pair: special; attribute 122 triple: generic; special; attribute 123 124Some of the type descriptions below contain a paragraph listing 'special 125attributes.' These are attributes that provide access to the implementation and 126are not intended for general use. Their definition may change in the future. 127 128None 129 .. index:: object: None 130 131 This type has a single value. There is a single object with this value. This 132 object is accessed through the built-in name ``None``. It is used to signify the 133 absence of a value in many situations, e.g., it is returned from functions that 134 don't explicitly return anything. Its truth value is false. 135 136NotImplemented 137 .. index:: object: NotImplemented 138 139 This type has a single value. There is a single object with this value. This 140 object is accessed through the built-in name ``NotImplemented``. Numeric methods 141 and rich comparison methods may return this value if they do not implement the 142 operation for the operands provided. (The interpreter will then try the 143 reflected operation, or some other fallback, depending on the operator.) Its 144 truth value is true. 145 146Ellipsis 147 .. index:: object: Ellipsis 148 149 This type has a single value. There is a single object with this value. This 150 object is accessed through the built-in name ``Ellipsis``. It is used to 151 indicate the presence of the ``...`` syntax in a slice. Its truth value is 152 true. 153 154:class:`numbers.Number` 155 .. index:: object: numeric 156 157 These are created by numeric literals and returned as results by arithmetic 158 operators and arithmetic built-in functions. Numeric objects are immutable; 159 once created their value never changes. Python numbers are of course strongly 160 related to mathematical numbers, but subject to the limitations of numerical 161 representation in computers. 162 163 Python distinguishes between integers, floating point numbers, and complex 164 numbers: 165 166 :class:`numbers.Integral` 167 .. index:: object: integer 168 169 These represent elements from the mathematical set of integers (positive and 170 negative). 171 172 There are three types of integers: 173 174 Plain integers 175 .. index:: 176 object: plain integer 177 single: OverflowError (built-in exception) 178 179 These represent numbers in the range -2147483648 through 2147483647. 180 (The range may be larger on machines with a larger natural word size, 181 but not smaller.) When the result of an operation would fall outside 182 this range, the result is normally returned as a long integer (in some 183 cases, the exception :exc:`OverflowError` is raised instead). For the 184 purpose of shift and mask operations, integers are assumed to have a 185 binary, 2's complement notation using 32 or more bits, and hiding no 186 bits from the user (i.e., all 4294967296 different bit patterns 187 correspond to different values). 188 189 Long integers 190 .. index:: object: long integer 191 192 These represent numbers in an unlimited range, subject to available 193 (virtual) memory only. For the purpose of shift and mask operations, a 194 binary representation is assumed, and negative numbers are represented 195 in a variant of 2's complement which gives the illusion of an infinite 196 string of sign bits extending to the left. 197 198 Booleans 199 .. index:: 200 object: Boolean 201 single: False 202 single: True 203 204 These represent the truth values False and True. The two objects 205 representing the values False and True are the only Boolean objects. 206 The Boolean type is a subtype of plain integers, and Boolean values 207 behave like the values 0 and 1, respectively, in almost all contexts, 208 the exception being that when converted to a string, the strings 209 ``"False"`` or ``"True"`` are returned, respectively. 210 211 .. index:: pair: integer; representation 212 213 The rules for integer representation are intended to give the most 214 meaningful interpretation of shift and mask operations involving negative 215 integers and the least surprises when switching between the plain and long 216 integer domains. Any operation, if it yields a result in the plain 217 integer domain, will yield the same result in the long integer domain or 218 when using mixed operands. The switch between domains is transparent to 219 the programmer. 220 221 :class:`numbers.Real` (:class:`float`) 222 .. index:: 223 object: floating point 224 pair: floating point; number 225 pair: C; language 226 pair: Java; language 227 228 These represent machine-level double precision floating point numbers. You are 229 at the mercy of the underlying machine architecture (and C or Java 230 implementation) for the accepted range and handling of overflow. Python does not 231 support single-precision floating point numbers; the savings in processor and 232 memory usage that are usually the reason for using these is dwarfed by the 233 overhead of using objects in Python, so there is no reason to complicate the 234 language with two kinds of floating point numbers. 235 236 :class:`numbers.Complex` 237 .. index:: 238 object: complex 239 pair: complex; number 240 241 These represent complex numbers as a pair of machine-level double precision 242 floating point numbers. The same caveats apply as for floating point numbers. 243 The real and imaginary parts of a complex number ``z`` can be retrieved through 244 the read-only attributes ``z.real`` and ``z.imag``. 245 246Sequences 247 .. index:: 248 builtin: len 249 object: sequence 250 single: index operation 251 single: item selection 252 single: subscription 253 254 These represent finite ordered sets indexed by non-negative numbers. The 255 built-in function :func:`len` returns the number of items of a sequence. When 256 the length of a sequence is *n*, the index set contains the numbers 0, 1, 257 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. 258 259 .. index:: single: slicing 260 261 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such 262 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a 263 sequence of the same type. This implies that the index set is renumbered so 264 that it starts at 0. 265 266 .. index:: single: extended slicing 267 268 Some sequences also support "extended slicing" with a third "step" parameter: 269 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n* 270 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*. 271 272 Sequences are distinguished according to their mutability: 273 274 Immutable sequences 275 .. index:: 276 object: immutable sequence 277 object: immutable 278 279 An object of an immutable sequence type cannot change once it is created. (If 280 the object contains references to other objects, these other objects may be 281 mutable and may be changed; however, the collection of objects directly 282 referenced by an immutable object cannot change.) 283 284 The following types are immutable sequences: 285 286 Strings 287 .. index:: 288 builtin: chr 289 builtin: ord 290 object: string 291 single: character 292 single: byte 293 single: ASCII@ASCII 294 295 The items of a string are characters. There is no separate character type; a 296 character is represented by a string of one item. Characters represent (at 297 least) 8-bit bytes. The built-in functions :func:`chr` and :func:`ord` convert 298 between characters and nonnegative integers representing the byte values. Bytes 299 with the values 0-127 usually represent the corresponding ASCII values, but the 300 interpretation of values is up to the program. The string data type is also 301 used to represent arrays of bytes, e.g., to hold data read from a file. 302 303 .. index:: 304 single: ASCII@ASCII 305 single: EBCDIC 306 single: character set 307 pair: string; comparison 308 builtin: chr 309 builtin: ord 310 311 (On systems whose native character set is not ASCII, strings may use EBCDIC in 312 their internal representation, provided the functions :func:`chr` and 313 :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison 314 preserves the ASCII order. Or perhaps someone can propose a better rule?) 315 316 Unicode 317 .. index:: 318 builtin: unichr 319 builtin: ord 320 builtin: unicode 321 object: unicode 322 single: character 323 single: integer 324 single: Unicode 325 326 The items of a Unicode object are Unicode code units. A Unicode code unit is 327 represented by a Unicode object of one item and can hold either a 16-bit or 328 32-bit value representing a Unicode ordinal (the maximum value for the ordinal 329 is given in ``sys.maxunicode``, and depends on how Python is configured at 330 compile time). Surrogate pairs may be present in the Unicode object, and will 331 be reported as two separate items. The built-in functions :func:`unichr` and 332 :func:`ord` convert between code units and nonnegative integers representing the 333 Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to 334 other encodings are possible through the Unicode method :meth:`encode` and the 335 built-in function :func:`unicode`. 336 337 Tuples 338 .. index:: 339 object: tuple 340 pair: singleton; tuple 341 pair: empty; tuple 342 343 The items of a tuple are arbitrary Python objects. Tuples of two or more items 344 are formed by comma-separated lists of expressions. A tuple of one item (a 345 'singleton') can be formed by affixing a comma to an expression (an expression 346 by itself does not create a tuple, since parentheses must be usable for grouping 347 of expressions). An empty tuple can be formed by an empty pair of parentheses. 348 349 Mutable sequences 350 .. index:: 351 object: mutable sequence 352 object: mutable 353 pair: assignment; statement 354 single: delete 355 statement: del 356 single: subscription 357 single: slicing 358 359 Mutable sequences can be changed after they are created. The subscription and 360 slicing notations can be used as the target of assignment and :keyword:`del` 361 (delete) statements. 362 363 There is currently a single intrinsic mutable sequence type: 364 365 Lists 366 .. index:: object: list 367 368 The items of a list are arbitrary Python objects. Lists are formed by placing a 369 comma-separated list of expressions in square brackets. (Note that there are no 370 special cases needed to form lists of length 0 or 1.) 371 372 .. index:: module: array 373 374 The extension module :mod:`array` provides an additional example of a mutable 375 sequence type. 376 377Set types 378 .. index:: 379 builtin: len 380 object: set type 381 382 These represent unordered, finite sets of unique, immutable objects. As such, 383 they cannot be indexed by any subscript. However, they can be iterated over, and 384 the built-in function :func:`len` returns the number of items in a set. Common 385 uses for sets are fast membership testing, removing duplicates from a sequence, 386 and computing mathematical operations such as intersection, union, difference, 387 and symmetric difference. 388 389 For set elements, the same immutability rules apply as for dictionary keys. Note 390 that numeric types obey the normal rules for numeric comparison: if two numbers 391 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a 392 set. 393 394 There are currently two intrinsic set types: 395 396 Sets 397 .. index:: object: set 398 399 These represent a mutable set. They are created by the built-in :func:`set` 400 constructor and can be modified afterwards by several methods, such as 401 :meth:`add`. 402 403 Frozen sets 404 .. index:: object: frozenset 405 406 These represent an immutable set. They are created by the built-in 407 :func:`frozenset` constructor. As a frozenset is immutable and 408 :term:`hashable`, it can be used again as an element of another set, or as 409 a dictionary key. 410 411Mappings 412 .. index:: 413 builtin: len 414 single: subscription 415 object: mapping 416 417 These represent finite sets of objects indexed by arbitrary index sets. The 418 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping 419 ``a``; this can be used in expressions and as the target of assignments or 420 :keyword:`del` statements. The built-in function :func:`len` returns the number 421 of items in a mapping. 422 423 There is currently a single intrinsic mapping type: 424 425 Dictionaries 426 .. index:: object: dictionary 427 428 These represent finite sets of objects indexed by nearly arbitrary values. The 429 only types of values not acceptable as keys are values containing lists or 430 dictionaries or other mutable types that are compared by value rather than by 431 object identity, the reason being that the efficient implementation of 432 dictionaries requires a key's hash value to remain constant. Numeric types used 433 for keys obey the normal rules for numeric comparison: if two numbers compare 434 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index 435 the same dictionary entry. 436 437 Dictionaries are mutable; they can be created by the ``{...}`` notation (see 438 section :ref:`dict`). 439 440 .. index:: 441 module: dbm 442 module: gdbm 443 module: bsddb 444 445 The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide 446 additional examples of mapping types. 447 448Callable types 449 .. index:: 450 object: callable 451 pair: function; call 452 single: invocation 453 pair: function; argument 454 455 These are the types to which the function call operation (see section 456 :ref:`calls`) can be applied: 457 458 User-defined functions 459 .. index:: 460 pair: user-defined; function 461 object: function 462 object: user-defined function 463 464 A user-defined function object is created by a function definition (see 465 section :ref:`function`). It should be called with an argument list 466 containing the same number of items as the function's formal parameter 467 list. 468 469 Special attributes: 470 471 +-----------------------+-------------------------------+-----------+ 472 | Attribute | Meaning | | 473 +=======================+===============================+===========+ 474 | :attr:`func_doc` | The function's documentation | Writable | 475 | | string, or ``None`` if | | 476 | | unavailable | | 477 +-----------------------+-------------------------------+-----------+ 478 | :attr:`__doc__` | Another way of spelling | Writable | 479 | | :attr:`func_doc` | | 480 +-----------------------+-------------------------------+-----------+ 481 | :attr:`func_name` | The function's name | Writable | 482 +-----------------------+-------------------------------+-----------+ 483 | :attr:`__name__` | Another way of spelling | Writable | 484 | | :attr:`func_name` | | 485 +-----------------------+-------------------------------+-----------+ 486 | :attr:`__module__` | The name of the module the | Writable | 487 | | function was defined in, or | | 488 | | ``None`` if unavailable. | | 489 +-----------------------+-------------------------------+-----------+ 490 | :attr:`func_defaults` | A tuple containing default | Writable | 491 | | argument values for those | | 492 | | arguments that have defaults, | | 493 | | or ``None`` if no arguments | | 494 | | have a default value | | 495 +-----------------------+-------------------------------+-----------+ 496 | :attr:`func_code` | The code object representing | Writable | 497 | | the compiled function body. | | 498 +-----------------------+-------------------------------+-----------+ 499 | :attr:`func_globals` | A reference to the dictionary | Read-only | 500 | | that holds the function's | | 501 | | global variables --- the | | 502 | | global namespace of the | | 503 | | module in which the function | | 504 | | was defined. | | 505 +-----------------------+-------------------------------+-----------+ 506 | :attr:`func_dict` | The namespace supporting | Writable | 507 | | arbitrary function | | 508 | | attributes. | | 509 +-----------------------+-------------------------------+-----------+ 510 | :attr:`func_closure` | ``None`` or a tuple of cells | Read-only | 511 | | that contain bindings for the | | 512 | | function's free variables. | | 513 +-----------------------+-------------------------------+-----------+ 514 515 Most of the attributes labelled "Writable" check the type of the assigned value. 516 517 .. versionchanged:: 2.4 518 ``func_name`` is now writable. 519 520 Function objects also support getting and setting arbitrary attributes, which 521 can be used, for example, to attach metadata to functions. Regular attribute 522 dot-notation is used to get and set such attributes. *Note that the current 523 implementation only supports function attributes on user-defined functions. 524 Function attributes on built-in functions may be supported in the future.* 525 526 Additional information about a function's definition can be retrieved from its 527 code object; see the description of internal types below. 528 529 .. index:: 530 single: func_doc (function attribute) 531 single: __doc__ (function attribute) 532 single: __name__ (function attribute) 533 single: __module__ (function attribute) 534 single: __dict__ (function attribute) 535 single: func_defaults (function attribute) 536 single: func_closure (function attribute) 537 single: func_code (function attribute) 538 single: func_globals (function attribute) 539 single: func_dict (function attribute) 540 pair: global; namespace 541 542 User-defined methods 543 .. index:: 544 object: method 545 object: user-defined method 546 pair: user-defined; method 547 548 A user-defined method object combines a class, a class instance (or ``None``) 549 and any callable object (normally a user-defined function). 550 551 Special read-only attributes: :attr:`im_self` is the class instance object, 552 :attr:`im_func` is the function object; :attr:`im_class` is the class of 553 :attr:`im_self` for bound methods or the class that asked for the method for 554 unbound methods; :attr:`__doc__` is the method's documentation (same as 555 ``im_func.__doc__``); :attr:`__name__` is the method name (same as 556 ``im_func.__name__``); :attr:`__module__` is the name of the module the method 557 was defined in, or ``None`` if unavailable. 558 559 .. versionchanged:: 2.2 560 :attr:`im_self` used to refer to the class that defined the method. 561 562 .. versionchanged:: 2.6 563 For 3.0 forward-compatibility, :attr:`im_func` is also available as 564 :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`. 565 566 .. index:: 567 single: __doc__ (method attribute) 568 single: __name__ (method attribute) 569 single: __module__ (method attribute) 570 single: im_func (method attribute) 571 single: im_self (method attribute) 572 573 Methods also support accessing (but not setting) the arbitrary function 574 attributes on the underlying function object. 575 576 User-defined method objects may be created when getting an attribute of a class 577 (perhaps via an instance of that class), if that attribute is a user-defined 578 function object, an unbound user-defined method object, or a class method 579 object. When the attribute is a user-defined method object, a new method object 580 is only created if the class from which it is being retrieved is the same as, or 581 a derived class of, the class stored in the original method object; otherwise, 582 the original method object is used as it is. 583 584 .. index:: 585 single: im_class (method attribute) 586 single: im_func (method attribute) 587 single: im_self (method attribute) 588 589 When a user-defined method object is created by retrieving a user-defined 590 function object from a class, its :attr:`im_self` attribute is ``None`` 591 and the method object is said to be unbound. When one is created by 592 retrieving a user-defined function object from a class via one of its 593 instances, its :attr:`im_self` attribute is the instance, and the method 594 object is said to be bound. In either case, the new method's 595 :attr:`im_class` attribute is the class from which the retrieval takes 596 place, and its :attr:`im_func` attribute is the original function object. 597 598 .. index:: single: im_func (method attribute) 599 600 When a user-defined method object is created by retrieving another method object 601 from a class or instance, the behaviour is the same as for a function object, 602 except that the :attr:`im_func` attribute of the new instance is not the 603 original method object but its :attr:`im_func` attribute. 604 605 .. index:: 606 single: im_class (method attribute) 607 single: im_func (method attribute) 608 single: im_self (method attribute) 609 610 When a user-defined method object is created by retrieving a class method object 611 from a class or instance, its :attr:`im_self` attribute is the class itself (the 612 same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is 613 the function object underlying the class method. 614 615 When an unbound user-defined method object is called, the underlying function 616 (:attr:`im_func`) is called, with the restriction that the first argument must 617 be an instance of the proper class (:attr:`im_class`) or of a derived class 618 thereof. 619 620 When a bound user-defined method object is called, the underlying function 621 (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in 622 front of the argument list. For instance, when :class:`C` is a class which 623 contains a definition for a function :meth:`f`, and ``x`` is an instance of 624 :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``. 625 626 When a user-defined method object is derived from a class method object, the 627 "class instance" stored in :attr:`im_self` will actually be the class itself, so 628 that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)`` 629 where ``f`` is the underlying function. 630 631 Note that the transformation from function object to (unbound or bound) method 632 object happens each time the attribute is retrieved from the class or instance. 633 In some cases, a fruitful optimization is to assign the attribute to a local 634 variable and call that local variable. Also notice that this transformation only 635 happens for user-defined functions; other callable objects (and all non-callable 636 objects) are retrieved without transformation. It is also important to note 637 that user-defined functions which are attributes of a class instance are not 638 converted to bound methods; this *only* happens when the function is an 639 attribute of the class. 640 641 Generator functions 642 .. index:: 643 single: generator; function 644 single: generator; iterator 645 646 A function or method which uses the :keyword:`yield` statement (see section 647 :ref:`yield`) is called a :dfn:`generator 648 function`. Such a function, when called, always returns an iterator object 649 which can be used to execute the body of the function: calling the iterator's 650 :meth:`next` method will cause the function to execute until it provides a value 651 using the :keyword:`yield` statement. When the function executes a 652 :keyword:`return` statement or falls off the end, a :exc:`StopIteration` 653 exception is raised and the iterator will have reached the end of the set of 654 values to be returned. 655 656 Built-in functions 657 .. index:: 658 object: built-in function 659 object: function 660 pair: C; language 661 662 A built-in function object is a wrapper around a C function. Examples of 663 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a 664 standard built-in module). The number and type of the arguments are 665 determined by the C function. Special read-only attributes: 666 :attr:`__doc__` is the function's documentation string, or ``None`` if 667 unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is 668 set to ``None`` (but see the next item); :attr:`__module__` is the name of 669 the module the function was defined in or ``None`` if unavailable. 670 671 Built-in methods 672 .. index:: 673 object: built-in method 674 object: method 675 pair: built-in; method 676 677 This is really a different disguise of a built-in function, this time containing 678 an object passed to the C function as an implicit extra argument. An example of 679 a built-in method is ``alist.append()``, assuming *alist* is a list object. In 680 this case, the special read-only attribute :attr:`__self__` is set to the object 681 denoted by *list*. 682 683 Class Types 684 Class types, or "new-style classes," are callable. These objects normally act 685 as factories for new instances of themselves, but variations are possible for 686 class types that override :meth:`__new__`. The arguments of the call are passed 687 to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize 688 the new instance. 689 690 Classic Classes 691 .. index:: 692 single: __init__() (object method) 693 object: class 694 object: class instance 695 object: instance 696 pair: class object; call 697 698 Class objects are described below. When a class object is called, a new class 699 instance (also described below) is created and returned. This implies a call to 700 the class's :meth:`__init__` method if it has one. Any arguments are passed on 701 to the :meth:`__init__` method. If there is no :meth:`__init__` method, the 702 class must be called without arguments. 703 704 Class instances 705 Class instances are described below. Class instances are callable only when the 706 class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for 707 ``x.__call__(arguments)``. 708 709Modules 710 .. index:: 711 statement: import 712 object: module 713 714 Modules are imported by the :keyword:`import` statement (see section 715 :ref:`import`). A module object has a 716 namespace implemented by a dictionary object (this is the dictionary referenced 717 by the func_globals attribute of functions defined in the module). Attribute 718 references are translated to lookups in this dictionary, e.g., ``m.x`` is 719 equivalent to ``m.__dict__["x"]``. A module object does not contain the code 720 object used to initialize the module (since it isn't needed once the 721 initialization is done). 722 723 Attribute assignment updates the module's namespace dictionary, e.g., ``m.x = 724 1`` is equivalent to ``m.__dict__["x"] = 1``. 725 726 .. index:: single: __dict__ (module attribute) 727 728 Special read-only attribute: :attr:`__dict__` is the module's namespace as a 729 dictionary object. 730 731 .. index:: 732 single: __name__ (module attribute) 733 single: __doc__ (module attribute) 734 single: __file__ (module attribute) 735 pair: module; namespace 736 737 Predefined (writable) attributes: :attr:`__name__` is the module's name; 738 :attr:`__doc__` is the module's documentation string, or ``None`` if 739 unavailable; :attr:`__file__` is the pathname of the file from which the module 740 was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not 741 present for C modules that are statically linked into the interpreter; for 742 extension modules loaded dynamically from a shared library, it is the pathname 743 of the shared library file. 744 745Classes 746 Both class types (new-style classes) and class objects (old-style/classic 747 classes) are typically created by class definitions (see section 748 :ref:`class`). A class has a namespace implemented by a dictionary object. 749 Class attribute references are translated to lookups in this dictionary, e.g., 750 ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes 751 in particular there are a number of hooks which allow for other means of 752 locating attributes). When the attribute name is not found there, the 753 attribute search continues in the base classes. For old-style classes, the 754 search is depth-first, left-to-right in the order of occurrence in the base 755 class list. New-style classes use the more complex C3 method resolution 756 order which behaves correctly even in the presence of 'diamond' 757 inheritance structures where there are multiple inheritance paths 758 leading back to a common ancestor. Additional details on the C3 MRO used by 759 new-style classes can be found in the documentation accompanying the 760 2.3 release at http://www.python.org/download/releases/2.3/mro/. 761 762 .. XXX: Could we add that MRO doc as an appendix to the language ref? 763 764 .. index:: 765 object: class 766 object: class instance 767 object: instance 768 pair: class object; call 769 single: container 770 object: dictionary 771 pair: class; attribute 772 773 When a class attribute reference (for class :class:`C`, say) would yield a 774 user-defined function object or an unbound user-defined method object whose 775 associated class is either :class:`C` or one of its base classes, it is 776 transformed into an unbound user-defined method object whose :attr:`im_class` 777 attribute is :class:`C`. When it would yield a class method object, it is 778 transformed into a bound user-defined method object whose :attr:`im_class` 779 and :attr:`im_self` attributes are both :class:`C`. When it would yield a 780 static method object, it is transformed into the object wrapped by the static 781 method object. See section :ref:`descriptors` for another way in which 782 attributes retrieved from a class may differ from those actually contained in 783 its :attr:`__dict__` (note that only new-style classes support descriptors). 784 785 .. index:: triple: class; attribute; assignment 786 787 Class attribute assignments update the class's dictionary, never the dictionary 788 of a base class. 789 790 .. index:: pair: class object; call 791 792 A class object can be called (see above) to yield a class instance (see below). 793 794 .. index:: 795 single: __name__ (class attribute) 796 single: __module__ (class attribute) 797 single: __dict__ (class attribute) 798 single: __bases__ (class attribute) 799 single: __doc__ (class attribute) 800 801 Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is 802 the module name in which the class was defined; :attr:`__dict__` is the 803 dictionary containing the class's namespace; :attr:`__bases__` is a tuple 804 (possibly empty or a singleton) containing the base classes, in the order of 805 their occurrence in the base class list; :attr:`__doc__` is the class's 806 documentation string, or None if undefined. 807 808Class instances 809 .. index:: 810 object: class instance 811 object: instance 812 pair: class; instance 813 pair: class instance; attribute 814 815 A class instance is created by calling a class object (see above). A class 816 instance has a namespace implemented as a dictionary which is the first place in 817 which attribute references are searched. When an attribute is not found there, 818 and the instance's class has an attribute by that name, the search continues 819 with the class attributes. If a class attribute is found that is a user-defined 820 function object or an unbound user-defined method object whose associated class 821 is the class (call it :class:`C`) of the instance for which the attribute 822 reference was initiated or one of its bases, it is transformed into a bound 823 user-defined method object whose :attr:`im_class` attribute is :class:`C` and 824 whose :attr:`im_self` attribute is the instance. Static method and class method 825 objects are also transformed, as if they had been retrieved from class 826 :class:`C`; see above under "Classes". See section :ref:`descriptors` for 827 another way in which attributes of a class retrieved via its instances may 828 differ from the objects actually stored in the class's :attr:`__dict__`. If no 829 class attribute is found, and the object's class has a :meth:`__getattr__` 830 method, that is called to satisfy the lookup. 831 832 .. index:: triple: class instance; attribute; assignment 833 834 Attribute assignments and deletions update the instance's dictionary, never a 835 class's dictionary. If the class has a :meth:`__setattr__` or 836 :meth:`__delattr__` method, this is called instead of updating the instance 837 dictionary directly. 838 839 .. index:: 840 object: numeric 841 object: sequence 842 object: mapping 843 844 Class instances can pretend to be numbers, sequences, or mappings if they have 845 methods with certain special names. See section :ref:`specialnames`. 846 847 .. index:: 848 single: __dict__ (instance attribute) 849 single: __class__ (instance attribute) 850 851 Special attributes: :attr:`__dict__` is the attribute dictionary; 852 :attr:`__class__` is the instance's class. 853 854Files 855 .. index:: 856 object: file 857 builtin: open 858 single: popen() (in module os) 859 single: makefile() (socket method) 860 single: sys.stdin 861 single: sys.stdout 862 single: sys.stderr 863 single: stdio 864 single: stdin (in module sys) 865 single: stdout (in module sys) 866 single: stderr (in module sys) 867 868 A file object represents an open file. File objects are created by the 869 :func:`open` built-in function, and also by :func:`os.popen`, 870 :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and 871 perhaps by other functions or methods provided by extension modules). The 872 objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to 873 file objects corresponding to the interpreter's standard input, output and 874 error streams. See :ref:`bltin-file-objects` for complete documentation of 875 file objects. 876 877Internal types 878 .. index:: 879 single: internal type 880 single: types, internal 881 882 A few types used internally by the interpreter are exposed to the user. Their 883 definitions may change with future versions of the interpreter, but they are 884 mentioned here for completeness. 885 886 Code objects 887 .. index:: 888 single: bytecode 889 object: code 890 891 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`. 892 The difference between a code object and a function object is that the function 893 object contains an explicit reference to the function's globals (the module in 894 which it was defined), while a code object contains no context; also the default 895 argument values are stored in the function object, not in the code object 896 (because they represent values calculated at run-time). Unlike function 897 objects, code objects are nearly immutable and contain no references (directly or 898 indirectly) to mutable objects. 899 900 Special read-only attributes: :attr:`co_name` gives the function name; 901 :attr:`co_argcount` is the number of positional arguments (including arguments 902 with default values); :attr:`co_nlocals` is the number of local variables used 903 by the function (including arguments); :attr:`co_varnames` is a tuple containing 904 the names of the local variables (starting with the argument names); 905 :attr:`co_cellvars` is a tuple containing the names of local variables that are 906 referenced by nested functions; :attr:`co_freevars` is a tuple containing the 907 names of free variables; :attr:`co_code` is a string representing the sequence 908 of bytecode instructions; :attr:`co_consts` is a tuple containing the literals 909 used by the bytecode; :attr:`co_names` is a tuple containing the names used by 910 the bytecode; :attr:`co_filename` is the filename from which the code was 911 compiled; :attr:`co_firstlineno` is the first line number of the function; 912 :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to line 913 numbers (for details see the source code of the interpreter); 914 :attr:`co_stacksize` is the required stack size (including local variables); 915 :attr:`co_flags` is an integer encoding a number of flags for the interpreter. 916 :attr:`co_llvm` refers to an llvm::Function wrapper that can pretty-print the 917 LLVM assembly that implements this code object. 918 919 Writable attributes: :attr:`co_use_jit` is ``True`` if LLVM will be used to 920 run this function, or ``False`` if the normal CPython interpreter will be used. 921 :attr:`co_optimization` is an integer from -1 to 2 recording how optimized 922 :attr:`co_llvm` is. -1 is totally unoptimized, and 0 is the default 923 optimization that happens before a function is JITted. You cannot lower the 924 optimization level of an already-optimized function. 925 926 .. index:: 927 single: co_argcount (code object attribute) 928 single: co_code (code object attribute) 929 single: co_consts (code object attribute) 930 single: co_filename (code object attribute) 931 single: co_firstlineno (code object attribute) 932 single: co_flags (code object attribute) 933 single: co_lnotab (code object attribute) 934 single: co_name (code object attribute) 935 single: co_names (code object attribute) 936 single: co_nlocals (code object attribute) 937 single: co_stacksize (code object attribute) 938 single: co_varnames (code object attribute) 939 single: co_cellvars (code object attribute) 940 single: co_freevars (code object attribute) 941 single: co_use_jit (code object attribute) 942 single: co_optimization (code object attribute) 943 single: co_llvm (code object attribute) 944 945 .. index:: object: generator 946 947 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if 948 the function uses the ``*arguments`` syntax to accept an arbitrary number of 949 positional arguments; bit ``0x08`` is set if the function uses the 950 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set 951 if the function is a generator. 952 953 Future feature declarations (``from __future__ import division``) also use bits 954 in :attr:`co_flags` to indicate whether a code object was compiled with a 955 particular feature enabled: bit ``0x2000`` is set if the function was compiled 956 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier 957 versions of Python. 958 959 Other bits in :attr:`co_flags` are reserved for internal use. 960 961 .. index:: single: documentation string 962 963 If a code object represents a function, the first item in :attr:`co_consts` is 964 the documentation string of the function, or ``None`` if undefined. 965 966 Frame objects 967 .. index:: object: frame 968 969 Frame objects represent execution frames. They may occur in traceback objects 970 (see below). 971 972 .. index:: 973 single: f_back (frame attribute) 974 single: f_code (frame attribute) 975 single: f_globals (frame attribute) 976 single: f_locals (frame attribute) 977 single: f_lasti (frame attribute) 978 single: f_builtins (frame attribute) 979 single: f_restricted (frame attribute) 980 981 Special read-only attributes: :attr:`f_back` is to the previous stack frame 982 (towards the caller), or ``None`` if this is the bottom stack frame; 983 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals` 984 is the dictionary used to look up local variables; :attr:`f_globals` is used for 985 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names; 986 :attr:`f_restricted` is a flag indicating whether the function is executing in 987 restricted execution mode; :attr:`f_lasti` gives the precise instruction (this 988 is an index into the bytecode string of the code object). 989 990 .. index:: 991 single: f_trace (frame attribute) 992 single: f_exc_type (frame attribute) 993 single: f_exc_value (frame attribute) 994 single: f_exc_traceback (frame attribute) 995 single: f_lineno (frame attribute) 996 997 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function 998 called at the start of each source code line (this is used by the debugger); 999 :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the 1000 last exception raised in the parent frame provided another exception was ever 1001 raised in the current frame (in all other cases they are None); :attr:`f_lineno` 1002 is the current line number of the frame --- writing to this from within a trace 1003 function jumps to the given line (only for the bottom-most frame). A debugger 1004 can implement a Jump command (aka Set Next Statement) by writing to f_lineno. 1005 1006 Traceback objects 1007 .. index:: 1008 object: traceback 1009 pair: stack; trace 1010 pair: exception; handler 1011 pair: execution; stack 1012 single: exc_info (in module sys) 1013 single: exc_traceback (in module sys) 1014 single: last_traceback (in module sys) 1015 single: sys.exc_info 1016 single: sys.exc_traceback 1017 single: sys.last_traceback 1018 1019 Traceback objects represent a stack trace of an exception. A traceback object 1020 is created when an exception occurs. When the search for an exception handler 1021 unwinds the execution stack, at each unwound level a traceback object is 1022 inserted in front of the current traceback. When an exception handler is 1023 entered, the stack trace is made available to the program. (See section 1024 :ref:`try`.) It is accessible as ``sys.exc_traceback``, 1025 and also as the third item of the tuple returned by ``sys.exc_info()``. The 1026 latter is the preferred interface, since it works correctly when the program is 1027 using multiple threads. When the program contains no suitable handler, the stack 1028 trace is written (nicely formatted) to the standard error stream; if the 1029 interpreter is interactive, it is also made available to the user as 1030 ``sys.last_traceback``. 1031 1032 .. index:: 1033 single: tb_next (traceback attribute) 1034 single: tb_frame (traceback attribute) 1035 single: tb_lineno (traceback attribute) 1036 single: tb_lasti (traceback attribute) 1037 statement: try 1038 1039 Special read-only attributes: :attr:`tb_next` is the next level in the stack 1040 trace (towards the frame where the exception occurred), or ``None`` if there is 1041 no next level; :attr:`tb_frame` points to the execution frame of the current 1042 level; :attr:`tb_lineno` gives the line number where the exception occurred; 1043 :attr:`tb_lasti` indicates the precise instruction. The line number and last 1044 instruction in the traceback may differ from the line number of its frame object 1045 if the exception occurred in a :keyword:`try` statement with no matching except 1046 clause or with a finally clause. 1047 1048 Slice objects 1049 .. index:: builtin: slice 1050 1051 Slice objects are used to represent slices when *extended slice syntax* is u…
Large files files are truncated, but you can click here to view the full file