PageRenderTime 111ms CodeModel.GetById 70ms app.highlight 27ms RepoModel.GetById 1ms app.codeStats 1ms

/Doc/reference/datamodel.rst

http://unladen-swallow.googlecode.com/
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