blob: ce7704ad0c45cd0039b63cccb5e94d4ffd5b6367 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001
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
Georg Brandl85eb8c12007-08-31 16:33:38 +000032.. XXX it *is* now possible in some cases to change an object's
33 type, under certain controlled conditions
34
Georg Brandl116aa622007-08-15 14:28:22 +000035Every object has an identity, a type and a value. An object's *identity* never
36changes once it has been created; you may think of it as the object's address in
37memory. The ':keyword:`is`' operator compares the identity of two objects; the
38:func:`id` function returns an integer representing its identity (currently
Georg Brandl85eb8c12007-08-31 16:33:38 +000039implemented as its address). An object's :dfn:`type` is also unchangeable.
Georg Brandl116aa622007-08-15 14:28:22 +000040An object's type determines the operations that the object supports (e.g., "does
41it have a length?") and also defines the possible values for objects of that
42type. The :func:`type` function returns an object's type (which is an object
43itself). The *value* of some objects can change. Objects whose value can
44change are said to be *mutable*; objects whose value is unchangeable once they
45are created are called *immutable*. (The value of an immutable container object
46that contains a reference to a mutable object can change when the latter's value
47is changed; however the container is still considered immutable, because the
48collection of objects it contains cannot be changed. So, immutability is not
49strictly the same as having an unchangeable value, it is more subtle.) An
50object's mutability is determined by its type; for instance, numbers, strings
51and tuples are immutable, while dictionaries and lists are mutable.
52
53.. index::
54 single: garbage collection
55 single: reference counting
56 single: unreachable object
57
58Objects are never explicitly destroyed; however, when they become unreachable
59they may be garbage-collected. An implementation is allowed to postpone garbage
60collection or omit it altogether --- it is a matter of implementation quality
61how garbage collection is implemented, as long as no objects are collected that
62are still reachable. (Implementation note: the current implementation uses a
63reference-counting scheme with (optional) delayed detection of cyclically linked
64garbage, which collects most objects as soon as they become unreachable, but is
65not guaranteed to collect garbage containing circular references. See the
66documentation of the :mod:`gc` module for information on controlling the
67collection of cyclic garbage.)
68
69Note that the use of the implementation's tracing or debugging facilities may
70keep objects alive that would normally be collectable. Also note that catching
71an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
72objects alive.
73
74Some objects contain references to "external" resources such as open files or
75windows. It is understood that these resources are freed when the object is
76garbage-collected, but since garbage collection is not guaranteed to happen,
77such objects also provide an explicit way to release the external resource,
78usually a :meth:`close` method. Programs are strongly recommended to explicitly
79close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement
80provides a convenient way to do this.
81
82.. index:: single: container
83
84Some objects contain references to other objects; these are called *containers*.
85Examples of containers are tuples, lists and dictionaries. The references are
86part of a container's value. In most cases, when we talk about the value of a
87container, we imply the values, not the identities of the contained objects;
88however, when we talk about the mutability of a container, only the identities
89of the immediately contained objects are implied. So, if an immutable container
90(like a tuple) contains a reference to a mutable object, its value changes if
91that mutable object is changed.
92
93Types affect almost all aspects of object behavior. Even the importance of
94object identity is affected in some sense: for immutable types, operations that
95compute new values may actually return a reference to any existing object with
96the same type and value, while for mutable objects this is not allowed. E.g.,
97after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
98with the value one, depending on the implementation, but after ``c = []; d =
99[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
100created empty lists. (Note that ``c = d = []`` assigns the same object to both
101``c`` and ``d``.)
102
103
104.. _types:
105
106The standard type hierarchy
107===========================
108
109.. index::
110 single: type
111 pair: data; type
112 pair: type; hierarchy
113 pair: extension; module
114 pair: C; language
115
116Below is a list of the types that are built into Python. Extension modules
117(written in C, Java, or other languages, depending on the implementation) can
118define additional types. Future versions of Python may add types to the type
119hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).
120
121.. index::
122 single: attribute
123 pair: special; attribute
124 triple: generic; special; attribute
125
126Some of the type descriptions below contain a paragraph listing 'special
127attributes.' These are attributes that provide access to the implementation and
128are not intended for general use. Their definition may change in the future.
129
130None
131 .. index:: object: None
132
133 This type has a single value. There is a single object with this value. This
134 object is accessed through the built-in name ``None``. It is used to signify the
135 absence of a value in many situations, e.g., it is returned from functions that
136 don't explicitly return anything. Its truth value is false.
137
138NotImplemented
139 .. index:: object: NotImplemented
140
141 This type has a single value. There is a single object with this value. This
142 object is accessed through the built-in name ``NotImplemented``. Numeric methods
143 and rich comparison methods may return this value if they do not implement the
144 operation for the operands provided. (The interpreter will then try the
145 reflected operation, or some other fallback, depending on the operator.) Its
146 truth value is true.
147
148Ellipsis
149 .. index:: object: Ellipsis
150
151 This type has a single value. There is a single object with this value. This
152 object is accessed through the literal ``...`` or the built-in name
153 ``Ellipsis``. Its truth value is true.
154
155Numbers
156 .. index:: object: numeric
157
158 These are created by numeric literals and returned as results by arithmetic
159 operators and arithmetic built-in functions. Numeric objects are immutable;
160 once created their value never changes. Python numbers are of course strongly
161 related to mathematical numbers, but subject to the limitations of numerical
162 representation in computers.
163
164 Python distinguishes between integers, floating point numbers, and complex
165 numbers:
166
167 Integers
168 .. index:: object: integer
169
170 These represent elements from the mathematical set of integers (positive and
171 negative).
172
173 There are three types of integers:
174
175 Plain integers
176 .. index::
177 object: plain integer
178 single: OverflowError (built-in exception)
179
180 These represent numbers in the range -2147483648 through 2147483647. (The range
181 may be larger on machines with a larger natural word size, but not smaller.)
182 When the result of an operation would fall outside this range, the result is
183 normally returned as a long integer (in some cases, the exception
184 :exc:`OverflowError` is raised instead). For the purpose of shift and mask
185 operations, integers are assumed to have a binary, 2's complement notation using
186 32 or more bits, and hiding no bits from the user (i.e., all 4294967296
187 different bit patterns 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 (virtual)
193 memory only. For the purpose of shift and mask operations, a binary
194 representation is assumed, and negative numbers are represented in a variant of
195 2's complement which gives the illusion of an infinite string of sign bits
196 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 representing
205 the values False and True are the only Boolean objects. The Boolean type is a
206 subtype of plain integers, and Boolean values behave like the values 0 and 1,
207 respectively, in almost all contexts, the exception being that when converted to
208 a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
209
210 .. index:: pair: integer; representation
211
212 The rules for integer representation are intended to give the most meaningful
213 interpretation of shift and mask operations involving negative integers and the
214 least surprises when switching between the plain and long integer domains. Any
215 operation except left shift, if it yields a result in the plain integer domain
216 without causing overflow, will yield the same result in the long integer domain
217 or when using mixed operands.
218
219 .. % Integers
220
221 Floating point numbers
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 Complex numbers
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
246 .. % Numbers
247
248Sequences
249 .. index::
250 builtin: len
251 object: sequence
252 single: index operation
253 single: item selection
254 single: subscription
255
256 These represent finite ordered sets indexed by non-negative numbers. The
257 built-in function :func:`len` returns the number of items of a sequence. When
258 the length of a sequence is *n*, the index set contains the numbers 0, 1,
259 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``.
260
261 .. index:: single: slicing
262
263 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
264 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
265 sequence of the same type. This implies that the index set is renumbered so
266 that it starts at 0.
267
268 .. index:: single: extended slicing
269
270 Some sequences also support "extended slicing" with a third "step" parameter:
271 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
272 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
273
274 Sequences are distinguished according to their mutability:
275
276 Immutable sequences
277 .. index::
278 object: immutable sequence
279 object: immutable
280
281 An object of an immutable sequence type cannot change once it is created. (If
282 the object contains references to other objects, these other objects may be
283 mutable and may be changed; however, the collection of objects directly
284 referenced by an immutable object cannot change.)
285
286 The following types are immutable sequences:
287
288 Strings
289 .. index::
290 builtin: chr
291 builtin: ord
Georg Brandldcc56f82007-08-31 16:41:12 +0000292 builtin: str
Georg Brandl116aa622007-08-15 14:28:22 +0000293 single: character
294 single: integer
295 single: Unicode
296
Georg Brandldcc56f82007-08-31 16:41:12 +0000297 The items of a string object are Unicode code units. A Unicode code
298 unit is represented by a string object of one item and can hold either
299 a 16-bit or 32-bit value representing a Unicode ordinal (the maximum
300 value for the ordinal is given in ``sys.maxunicode``, and depends on
301 how Python is configured at compile time). Surrogate pairs may be
302 present in the Unicode object, and will be reported as two separate
303 items. The built-in functions :func:`chr` and :func:`ord` convert
304 between code units and nonnegative integers representing the Unicode
305 ordinals as defined in the Unicode Standard 3.0. Conversion from and to
306 other encodings are possible through the string method :meth:`encode`.
Georg Brandl116aa622007-08-15 14:28:22 +0000307
308 Tuples
309 .. index::
310 object: tuple
311 pair: singleton; tuple
312 pair: empty; tuple
313
Georg Brandldcc56f82007-08-31 16:41:12 +0000314 The items of a tuple are arbitrary Python objects. Tuples of two or
315 more items are formed by comma-separated lists of expressions. A tuple
316 of one item (a 'singleton') can be formed by affixing a comma to an
317 expression (an expression by itself does not create a tuple, since
318 parentheses must be usable for grouping of expressions). An empty
319 tuple can be formed by an empty pair of parentheses.
Georg Brandl116aa622007-08-15 14:28:22 +0000320
321 .. % Immutable sequences
322
323 Mutable sequences
324 .. index::
325 object: mutable sequence
326 object: mutable
327 pair: assignment; statement
328 single: delete
329 statement: del
330 single: subscription
331 single: slicing
332
333 Mutable sequences can be changed after they are created. The subscription and
334 slicing notations can be used as the target of assignment and :keyword:`del`
335 (delete) statements.
336
337 There is currently a single intrinsic mutable sequence type:
338
339 Lists
340 .. index:: object: list
341
Georg Brandldcc56f82007-08-31 16:41:12 +0000342 The items of a list are arbitrary Python objects. Lists are formed by
343 placing a comma-separated list of expressions in square brackets. (Note
344 that there are no special cases needed to form lists of length 0 or 1.)
345
346 Bytes
347 .. index:: bytes, byte
348
349 A bytes object is a mutable array. The items are 8-bit bytes,
350 represented by integers in the range 0 <= x < 256. Bytes literals
351 (like ``b'abc'`` and the built-in function :func:`bytes` can be used to
352 construct bytes objects. Also, bytes objects can be decoded to strings
353 via the :meth:`decode` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000354
355 .. index:: module: array
356
Georg Brandldcc56f82007-08-31 16:41:12 +0000357 The extension module :mod:`array` provides an additional example of a
358 mutable sequence type.
Georg Brandl116aa622007-08-15 14:28:22 +0000359
360 .. % Mutable sequences
361
362 .. % Sequences
363
364Set types
365 .. index::
366 builtin: len
367 object: set type
368
369 These represent unordered, finite sets of unique, immutable objects. As such,
370 they cannot be indexed by any subscript. However, they can be iterated over, and
371 the built-in function :func:`len` returns the number of items in a set. Common
372 uses for sets are fast membership testing, removing duplicates from a sequence,
373 and computing mathematical operations such as intersection, union, difference,
374 and symmetric difference.
375
376 For set elements, the same immutability rules apply as for dictionary keys. Note
377 that numeric types obey the normal rules for numeric comparison: if two numbers
378 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
379 set.
380
381 There are currently two intrinsic set types:
382
383 Sets
384 .. index:: object: set
385
386 These represent a mutable set. They are created by the built-in :func:`set`
387 constructor and can be modified afterwards by several methods, such as
388 :meth:`add`.
389
390 Frozen sets
391 .. index:: object: frozenset
392
393 These represent an immutable set. They are created by the built-in
394 :func:`frozenset` constructor. As a frozenset is immutable and hashable, it can
395 be used again as an element of another set, or as a dictionary key.
396
397 .. % Set types
398
399Mappings
400 .. index::
401 builtin: len
402 single: subscription
403 object: mapping
404
405 These represent finite sets of objects indexed by arbitrary index sets. The
406 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
407 ``a``; this can be used in expressions and as the target of assignments or
408 :keyword:`del` statements. The built-in function :func:`len` returns the number
409 of items in a mapping.
410
411 There is currently a single intrinsic mapping type:
412
413 Dictionaries
414 .. index:: object: dictionary
415
416 These represent finite sets of objects indexed by nearly arbitrary values. The
417 only types of values not acceptable as keys are values containing lists or
418 dictionaries or other mutable types that are compared by value rather than by
419 object identity, the reason being that the efficient implementation of
420 dictionaries requires a key's hash value to remain constant. Numeric types used
421 for keys obey the normal rules for numeric comparison: if two numbers compare
422 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
423 the same dictionary entry.
424
425 Dictionaries are mutable; they can be created by the ``{...}`` notation (see
426 section :ref:`dict`).
427
428 .. index::
429 module: dbm
430 module: gdbm
431 module: bsddb
432
433 The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
434 additional examples of mapping types.
435
436 .. % Mapping types
437
438Callable types
439 .. index::
440 object: callable
441 pair: function; call
442 single: invocation
443 pair: function; argument
444
445 These are the types to which the function call operation (see section
446 :ref:`calls`) can be applied:
447
448 User-defined functions
449 .. index::
450 pair: user-defined; function
451 object: function
452 object: user-defined function
453
454 A user-defined function object is created by a function definition (see
455 section :ref:`function`). It should be called with an argument list
456 containing the same number of items as the function's formal parameter
457 list.
458
459 Special attributes:
460
461 +-------------------------+-------------------------------+-----------+
462 | Attribute | Meaning | |
463 +=========================+===============================+===========+
464 | :attr:`__doc__` | The function's documentation | Writable |
465 | | string, or ``None`` if | |
466 | | unavailable | |
467 +-------------------------+-------------------------------+-----------+
468 | :attr:`__name__` | The function's name | Writable |
469 +-------------------------+-------------------------------+-----------+
470 | :attr:`__module__` | The name of the module the | Writable |
471 | | function was defined in, or | |
472 | | ``None`` if unavailable. | |
473 +-------------------------+-------------------------------+-----------+
474 | :attr:`__defaults__` | A tuple containing default | Writable |
475 | | argument values for those | |
476 | | arguments that have defaults, | |
477 | | or ``None`` if no arguments | |
478 | | have a default value | |
479 +-------------------------+-------------------------------+-----------+
480 | :attr:`__code__` | The code object representing | Writable |
481 | | the compiled function body. | |
482 +-------------------------+-------------------------------+-----------+
483 | :attr:`__globals__` | A reference to the dictionary | Read-only |
484 | | that holds the function's | |
485 | | global variables --- the | |
486 | | global namespace of the | |
487 | | module in which the function | |
488 | | was defined. | |
489 +-------------------------+-------------------------------+-----------+
490 | :attr:`__dict__` | The namespace supporting | Writable |
491 | | arbitrary function | |
492 | | attributes. | |
493 +-------------------------+-------------------------------+-----------+
494 | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only |
495 | | that contain bindings for the | |
496 | | function's free variables. | |
497 +-------------------------+-------------------------------+-----------+
498 | :attr:`__annotations__` | A dict containing annotations | Writable |
499 | | of parameters. The keys of | |
500 | | the dict are the parameter | |
501 | | names, or ``'return'`` for | |
502 | | the return annotation, if | |
503 | | provided. | |
504 +-------------------------+-------------------------------+-----------+
505 | :attr:`__kwdefaults__` | A dict containing defaults | Writable |
506 | | for keyword-only parameters. | |
507 +-------------------------+-------------------------------+-----------+
508
509 Most of the attributes labelled "Writable" check the type of the assigned value.
510
511 .. versionchanged:: 2.4
512 ``__name__`` is now writable.
513
514 Function objects also support getting and setting arbitrary attributes, which
515 can be used, for example, to attach metadata to functions. Regular attribute
516 dot-notation is used to get and set such attributes. *Note that the current
517 implementation only supports function attributes on user-defined functions.
518 Function attributes on built-in functions may be supported in the future.*
519
520 Additional information about a function's definition can be retrieved from its
521 code object; see the description of internal types below.
522
523 .. index::
524 single: __doc__ (function attribute)
525 single: __name__ (function attribute)
526 single: __module__ (function attribute)
527 single: __dict__ (function attribute)
528 single: __defaults__ (function attribute)
529 single: __closure__ (function attribute)
530 single: __code__ (function attribute)
531 single: __globals__ (function attribute)
532 single: __annotations__ (function attribute)
533 single: __kwdefaults__ (function attribute)
534 pair: global; namespace
535
536 User-defined methods
537 .. index::
538 object: method
539 object: user-defined method
540 pair: user-defined; method
541
542 A user-defined method object combines a class, a class instance (or ``None``)
543 and any callable object (normally a user-defined function).
544
545 Special read-only attributes: :attr:`im_self` is the class instance object,
546 :attr:`im_func` is the function object; :attr:`im_class` is the class of
547 :attr:`im_self` for bound methods or the class that asked for the method for
548 unbound methods; :attr:`__doc__` is the method's documentation (same as
549 ``im_func.__doc__``); :attr:`__name__` is the method name (same as
550 ``im_func.__name__``); :attr:`__module__` is the name of the module the method
551 was defined in, or ``None`` if unavailable.
552
553 .. versionchanged:: 2.2
554 :attr:`im_self` used to refer to the class that defined the method.
555
556 .. index::
557 single: __doc__ (method attribute)
558 single: __name__ (method attribute)
559 single: __module__ (method attribute)
560 single: im_func (method attribute)
561 single: im_self (method attribute)
562
563 Methods also support accessing (but not setting) the arbitrary function
564 attributes on the underlying function object.
565
566 User-defined method objects may be created when getting an attribute of a class
567 (perhaps via an instance of that class), if that attribute is a user-defined
568 function object, an unbound user-defined method object, or a class method
569 object. When the attribute is a user-defined method object, a new method object
570 is only created if the class from which it is being retrieved is the same as, or
571 a derived class of, the class stored in the original method object; otherwise,
572 the original method object is used as it is.
573
574 .. index::
575 single: im_class (method attribute)
576 single: im_func (method attribute)
577 single: im_self (method attribute)
578
579 When a user-defined method object is created by retrieving a user-defined
580 function object from a class, its :attr:`im_self` attribute is ``None``
581 and the method object is said to be unbound. When one is created by
582 retrieving a user-defined function object from a class via one of its
583 instances, its :attr:`im_self` attribute is the instance, and the method
584 object is said to be bound. In either case, the new method's
585 :attr:`im_class` attribute is the class from which the retrieval takes
586 place, and its :attr:`im_func` attribute is the original function object.
587
588 .. index:: single: im_func (method attribute)
589
590 When a user-defined method object is created by retrieving another method object
591 from a class or instance, the behaviour is the same as for a function object,
592 except that the :attr:`im_func` attribute of the new instance is not the
593 original method object but its :attr:`im_func` attribute.
594
595 .. index::
596 single: im_class (method attribute)
597 single: im_func (method attribute)
598 single: im_self (method attribute)
599
600 When a user-defined method object is created by retrieving a class method object
601 from a class or instance, its :attr:`im_self` attribute is the class itself (the
602 same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is
603 the function object underlying the class method.
604
605 When an unbound user-defined method object is called, the underlying function
606 (:attr:`im_func`) is called, with the restriction that the first argument must
607 be an instance of the proper class (:attr:`im_class`) or of a derived class
608 thereof.
609
610 When a bound user-defined method object is called, the underlying function
611 (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in
612 front of the argument list. For instance, when :class:`C` is a class which
613 contains a definition for a function :meth:`f`, and ``x`` is an instance of
614 :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``.
615
616 When a user-defined method object is derived from a class method object, the
617 "class instance" stored in :attr:`im_self` will actually be the class itself, so
618 that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)``
619 where ``f`` is the underlying function.
620
621 Note that the transformation from function object to (unbound or bound) method
622 object happens each time the attribute is retrieved from the class or instance.
623 In some cases, a fruitful optimization is to assign the attribute to a local
624 variable and call that local variable. Also notice that this transformation only
625 happens for user-defined functions; other callable objects (and all non-callable
626 objects) are retrieved without transformation. It is also important to note
627 that user-defined functions which are attributes of a class instance are not
628 converted to bound methods; this *only* happens when the function is an
629 attribute of the class.
630
631 Generator functions
632 .. index::
633 single: generator; function
634 single: generator; iterator
635
636 A function or method which uses the :keyword:`yield` statement (see section
637 :ref:`yield`) is called a :dfn:`generator
638 function`. Such a function, when called, always returns an iterator object
639 which can be used to execute the body of the function: calling the iterator's
640 :meth:`__next__` method will cause the function to execute until it provides a
641 value using the :keyword:`yield` statement. When the function executes a
642 :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
643 exception is raised and the iterator will have reached the end of the set of
644 values to be returned.
645
646 Built-in functions
647 .. index::
648 object: built-in function
649 object: function
650 pair: C; language
651
652 A built-in function object is a wrapper around a C function. Examples of
653 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
654 standard built-in module). The number and type of the arguments are
655 determined by the C function. Special read-only attributes:
656 :attr:`__doc__` is the function's documentation string, or ``None`` if
657 unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
658 set to ``None`` (but see the next item); :attr:`__module__` is the name of
659 the module the function was defined in or ``None`` if unavailable.
660
661 Built-in methods
662 .. index::
663 object: built-in method
664 object: method
665 pair: built-in; method
666
667 This is really a different disguise of a built-in function, this time containing
668 an object passed to the C function as an implicit extra argument. An example of
669 a built-in method is ``alist.append()``, assuming *alist* is a list object. In
670 this case, the special read-only attribute :attr:`__self__` is set to the object
671 denoted by *list*.
672
Georg Brandl85eb8c12007-08-31 16:33:38 +0000673 Classes
674 Classes are callable. These objects normally act as factories for new
675 instances of themselves, but variations are possible for class types that
676 override :meth:`__new__`. The arguments of the call are passed to
677 :meth:`__new__` and, in the typical case, to :meth:`__init__` to
678 initialize the new instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000679
Georg Brandl85eb8c12007-08-31 16:33:38 +0000680 Class Instances
681 Instances of arbitrary classes can be made callable by defining a
682 :meth:`__call__` method in their class.
Georg Brandl116aa622007-08-15 14:28:22 +0000683
Georg Brandl116aa622007-08-15 14:28:22 +0000684
685Modules
686 .. index::
687 statement: import
688 object: module
689
690 Modules are imported by the :keyword:`import` statement (see section
691 :ref:`import`). A module object has a
692 namespace implemented by a dictionary object (this is the dictionary referenced
693 by the __globals__ attribute of functions defined in the module). Attribute
694 references are translated to lookups in this dictionary, e.g., ``m.x`` is
695 equivalent to ``m.__dict__["x"]``. A module object does not contain the code
696 object used to initialize the module (since it isn't needed once the
697 initialization is done).
698
699 .. %
700
701 Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
702 1`` is equivalent to ``m.__dict__["x"] = 1``.
703
704 .. index:: single: __dict__ (module attribute)
705
706 Special read-only attribute: :attr:`__dict__` is the module's namespace as a
707 dictionary object.
708
709 .. index::
710 single: __name__ (module attribute)
711 single: __doc__ (module attribute)
712 single: __file__ (module attribute)
713 pair: module; namespace
714
715 Predefined (writable) attributes: :attr:`__name__` is the module's name;
716 :attr:`__doc__` is the module's documentation string, or ``None`` if
717 unavailable; :attr:`__file__` is the pathname of the file from which the module
718 was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
719 present for C modules that are statically linked into the interpreter; for
720 extension modules loaded dynamically from a shared library, it is the pathname
721 of the shared library file.
722
Georg Brandl85eb8c12007-08-31 16:33:38 +0000723.. XXX "Classes" and "Instances" is outdated!
724 see http://www.python.org/doc/newstyle.html for newstyle information
725
726Custom classes
Georg Brandl116aa622007-08-15 14:28:22 +0000727 Class objects are created by class definitions (see section :ref:`class`). A
728 class has a namespace implemented by a dictionary object. Class attribute
729 references are translated to lookups in this dictionary, e.g., ``C.x`` is
730 translated to ``C.__dict__["x"]``. When the attribute name is not found
731 there, the attribute search continues in the base classes. The search is
732 depth-first, left-to-right in the order of occurrence in the base class list.
733
Georg Brandl85eb8c12007-08-31 16:33:38 +0000734 .. XXX document descriptors and new MRO
735
Georg Brandl116aa622007-08-15 14:28:22 +0000736 .. index::
737 object: class
738 object: class instance
739 object: instance
740 pair: class object; call
741 single: container
742 object: dictionary
743 pair: class; attribute
744
745 When a class attribute reference (for class :class:`C`, say) would yield a
746 user-defined function object or an unbound user-defined method object whose
747 associated class is either :class:`C` or one of its base classes, it is
748 transformed into an unbound user-defined method object whose :attr:`im_class`
749 attribute is :class:`C`. When it would yield a class method object, it is
750 transformed into a bound user-defined method object whose :attr:`im_class`
751 and :attr:`im_self` attributes are both :class:`C`. When it would yield a
752 static method object, it is transformed into the object wrapped by the static
753 method object. See section :ref:`descriptors` for another way in which
754 attributes retrieved from a class may differ from those actually contained in
755 its :attr:`__dict__`.
756
757 .. index:: triple: class; attribute; assignment
758
759 Class attribute assignments update the class's dictionary, never the dictionary
760 of a base class.
761
762 .. index:: pair: class object; call
763
764 A class object can be called (see above) to yield a class instance (see below).
765
766 .. index::
767 single: __name__ (class attribute)
768 single: __module__ (class attribute)
769 single: __dict__ (class attribute)
770 single: __bases__ (class attribute)
771 single: __doc__ (class attribute)
772
773 Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
774 the module name in which the class was defined; :attr:`__dict__` is the
775 dictionary containing the class's namespace; :attr:`__bases__` is a tuple
776 (possibly empty or a singleton) containing the base classes, in the order of
777 their occurrence in the base class list; :attr:`__doc__` is the class's
778 documentation string, or None if undefined.
779
780Class instances
781 .. index::
782 object: class instance
783 object: instance
784 pair: class; instance
785 pair: class instance; attribute
786
787 A class instance is created by calling a class object (see above). A class
788 instance has a namespace implemented as a dictionary which is the first place in
789 which attribute references are searched. When an attribute is not found there,
790 and the instance's class has an attribute by that name, the search continues
791 with the class attributes. If a class attribute is found that is a user-defined
792 function object or an unbound user-defined method object whose associated class
793 is the class (call it :class:`C`) of the instance for which the attribute
794 reference was initiated or one of its bases, it is transformed into a bound
795 user-defined method object whose :attr:`im_class` attribute is :class:`C` and
796 whose :attr:`im_self` attribute is the instance. Static method and class method
797 objects are also transformed, as if they had been retrieved from class
798 :class:`C`; see above under "Classes". See section :ref:`descriptors` for
799 another way in which attributes of a class retrieved via its instances may
800 differ from the objects actually stored in the class's :attr:`__dict__`. If no
801 class attribute is found, and the object's class has a :meth:`__getattr__`
802 method, that is called to satisfy the lookup.
803
804 .. index:: triple: class instance; attribute; assignment
805
806 Attribute assignments and deletions update the instance's dictionary, never a
807 class's dictionary. If the class has a :meth:`__setattr__` or
808 :meth:`__delattr__` method, this is called instead of updating the instance
809 dictionary directly.
810
811 .. index::
812 object: numeric
813 object: sequence
814 object: mapping
815
816 Class instances can pretend to be numbers, sequences, or mappings if they have
817 methods with certain special names. See section :ref:`specialnames`.
818
819 .. index::
820 single: __dict__ (instance attribute)
821 single: __class__ (instance attribute)
822
823 Special attributes: :attr:`__dict__` is the attribute dictionary;
824 :attr:`__class__` is the instance's class.
825
826Files
827 .. index::
828 object: file
829 builtin: open
830 single: popen() (in module os)
831 single: makefile() (socket method)
832 single: sys.stdin
833 single: sys.stdout
834 single: sys.stderr
835 single: stdio
836 single: stdin (in module sys)
837 single: stdout (in module sys)
838 single: stderr (in module sys)
839
840 A file object represents an open file. File objects are created by the
841 :func:`open` built-in function, and also by :func:`os.popen`,
842 :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and
843 perhaps by other functions or methods provided by extension modules). The
844 objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to
845 file objects corresponding to the interpreter's standard input, output and
846 error streams. See :ref:`bltin-file-objects` for complete documentation of
847 file objects.
848
849Internal types
850 .. index::
851 single: internal type
852 single: types, internal
853
854 A few types used internally by the interpreter are exposed to the user. Their
855 definitions may change with future versions of the interpreter, but they are
856 mentioned here for completeness.
857
858 Code objects
859 .. index::
860 single: bytecode
861 object: code
862
863 Code objects represent *byte-compiled* executable Python code, or *bytecode*.
864 The difference between a code object and a function object is that the function
865 object contains an explicit reference to the function's globals (the module in
866 which it was defined), while a code object contains no context; also the default
867 argument values are stored in the function object, not in the code object
868 (because they represent values calculated at run-time). Unlike function
869 objects, code objects are immutable and contain no references (directly or
870 indirectly) to mutable objects.
871
872 Special read-only attributes: :attr:`co_name` gives the function name;
873 :attr:`co_argcount` is the number of positional arguments (including arguments
874 with default values); :attr:`co_nlocals` is the number of local variables used
875 by the function (including arguments); :attr:`co_varnames` is a tuple containing
876 the names of the local variables (starting with the argument names);
877 :attr:`co_cellvars` is a tuple containing the names of local variables that are
878 referenced by nested functions; :attr:`co_freevars` is a tuple containing the
879 names of free variables; :attr:`co_code` is a string representing the sequence
880 of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
881 used by the bytecode; :attr:`co_names` is a tuple containing the names used by
882 the bytecode; :attr:`co_filename` is the filename from which the code was
883 compiled; :attr:`co_firstlineno` is the first line number of the function;
884 :attr:`co_lnotab` is a string encoding the mapping from byte code offsets to
885 line numbers (for details see the source code of the interpreter);
886 :attr:`co_stacksize` is the required stack size (including local variables);
887 :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
888
889 .. index::
890 single: co_argcount (code object attribute)
891 single: co_code (code object attribute)
892 single: co_consts (code object attribute)
893 single: co_filename (code object attribute)
894 single: co_firstlineno (code object attribute)
895 single: co_flags (code object attribute)
896 single: co_lnotab (code object attribute)
897 single: co_name (code object attribute)
898 single: co_names (code object attribute)
899 single: co_nlocals (code object attribute)
900 single: co_stacksize (code object attribute)
901 single: co_varnames (code object attribute)
902 single: co_cellvars (code object attribute)
903 single: co_freevars (code object attribute)
904
905 .. index:: object: generator
906
907 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
908 the function uses the ``*arguments`` syntax to accept an arbitrary number of
909 positional arguments; bit ``0x08`` is set if the function uses the
910 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
911 if the function is a generator.
912
913 Future feature declarations (``from __future__ import division``) also use bits
914 in :attr:`co_flags` to indicate whether a code object was compiled with a
915 particular feature enabled: bit ``0x2000`` is set if the function was compiled
916 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
917 versions of Python.
918
919 Other bits in :attr:`co_flags` are reserved for internal use.
920
921 .. index:: single: documentation string
922
923 If a code object represents a function, the first item in :attr:`co_consts` is
924 the documentation string of the function, or ``None`` if undefined.
925
926 Frame objects
927 .. index:: object: frame
928
929 Frame objects represent execution frames. They may occur in traceback objects
930 (see below).
931
932 .. index::
933 single: f_back (frame attribute)
934 single: f_code (frame attribute)
935 single: f_globals (frame attribute)
936 single: f_locals (frame attribute)
937 single: f_lasti (frame attribute)
938 single: f_builtins (frame attribute)
939
940 Special read-only attributes: :attr:`f_back` is to the previous stack frame
941 (towards the caller), or ``None`` if this is the bottom stack frame;
942 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
943 is the dictionary used to look up local variables; :attr:`f_globals` is used for
944 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
945 :attr:`f_lasti` gives the precise instruction (this is an index into the
946 bytecode string of the code object).
947
948 .. index::
949 single: f_trace (frame attribute)
950 single: f_exc_type (frame attribute)
951 single: f_exc_value (frame attribute)
952 single: f_exc_traceback (frame attribute)
953 single: f_lineno (frame attribute)
954
955 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
956 called at the start of each source code line (this is used by the debugger);
957 :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the
958 last exception raised in the parent frame provided another exception was ever
959 raised in the current frame (in all other cases they are None); :attr:`f_lineno`
960 is the current line number of the frame --- writing to this from within a trace
961 function jumps to the given line (only for the bottom-most frame). A debugger
962 can implement a Jump command (aka Set Next Statement) by writing to f_lineno.
963
964 Traceback objects
965 .. index::
966 object: traceback
967 pair: stack; trace
968 pair: exception; handler
969 pair: execution; stack
970 single: exc_info (in module sys)
971 single: exc_traceback (in module sys)
972 single: last_traceback (in module sys)
973 single: sys.exc_info
974 single: sys.last_traceback
975
976 Traceback objects represent a stack trace of an exception. A traceback object
977 is created when an exception occurs. When the search for an exception handler
978 unwinds the execution stack, at each unwound level a traceback object is
979 inserted in front of the current traceback. When an exception handler is
980 entered, the stack trace is made available to the program. (See section
981 :ref:`try`.) It is accessible as the third item of the
982 tuple returned by ``sys.exc_info()``. When the program contains no suitable
983 handler, the stack trace is written (nicely formatted) to the standard error
984 stream; if the interpreter is interactive, it is also made available to the user
985 as ``sys.last_traceback``.
986
987 .. index::
988 single: tb_next (traceback attribute)
989 single: tb_frame (traceback attribute)
990 single: tb_lineno (traceback attribute)
991 single: tb_lasti (traceback attribute)
992 statement: try
993
994 Special read-only attributes: :attr:`tb_next` is the next level in the stack
995 trace (towards the frame where the exception occurred), or ``None`` if there is
996 no next level; :attr:`tb_frame` points to the execution frame of the current
997 level; :attr:`tb_lineno` gives the line number where the exception occurred;
998 :attr:`tb_lasti` indicates the precise instruction. The line number and last
999 instruction in the traceback may differ from the line number of its frame object
1000 if the exception occurred in a :keyword:`try` statement with no matching except
1001 clause or with a finally clause.
1002
1003 Slice objects
1004 .. index:: builtin: slice
1005
1006 Slice objects are used to represent slices when *extended slice syntax* is used.
1007 This is a slice using two colons, or multiple slices or ellipses separated by
1008 commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``. They are
1009 also created by the built-in :func:`slice` function.
1010
1011 .. index::
1012 single: start (slice object attribute)
1013 single: stop (slice object attribute)
1014 single: step (slice object attribute)
1015
1016 Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is
1017 the upper bound; :attr:`step` is the step value; each is ``None`` if omitted.
1018 These attributes can have any type.
1019
1020 Slice objects support one method:
1021
1022
1023 .. method:: slice.indices(self, length)
1024
1025 This method takes a single integer argument *length* and computes information
1026 about the extended slice that the slice object would describe if applied to a
1027 sequence of *length* items. It returns a tuple of three integers; respectively
1028 these are the *start* and *stop* indices and the *step* or stride length of the
1029 slice. Missing or out-of-bounds indices are handled in a manner consistent with
1030 regular slices.
1031
1032 .. versionadded:: 2.3
1033
1034 Static method objects
1035 Static method objects provide a way of defeating the transformation of function
1036 objects to method objects described above. A static method object is a wrapper
1037 around any other object, usually a user-defined method object. When a static
1038 method object is retrieved from a class or a class instance, the object actually
1039 returned is the wrapped object, which is not subject to any further
1040 transformation. Static method objects are not themselves callable, although the
1041 objects they wrap usually are. Static method objects are created by the built-in
1042 :func:`staticmethod` constructor.
1043
1044 Class method objects
1045 A class method object, like a static method object, is a wrapper around another
1046 object that alters the way in which that object is retrieved from classes and
1047 class instances. The behaviour of class method objects upon such retrieval is
1048 described above, under "User-defined methods". Class method objects are created
1049 by the built-in :func:`classmethod` constructor.
1050
1051 .. % Internal types
1052
Georg Brandl116aa622007-08-15 14:28:22 +00001053.. % =========================================================================
1054
1055
1056.. _specialnames:
1057
1058Special method names
1059====================
1060
1061.. index::
1062 pair: operator; overloading
1063 single: __getitem__() (mapping object method)
1064
1065A class can implement certain operations that are invoked by special syntax
1066(such as arithmetic operations or subscripting and slicing) by defining methods
1067with special names. This is Python's approach to :dfn:`operator overloading`,
1068allowing classes to define their own behavior with respect to language
1069operators. For instance, if a class defines a method named :meth:`__getitem__`,
Georg Brandl85eb8c12007-08-31 16:33:38 +00001070and ``x`` is an instance of this class, then ``x[i]`` is equivalent to
Georg Brandl116aa622007-08-15 14:28:22 +00001071``x.__getitem__(i)``. Except where mentioned, attempts to execute an operation
1072raise an exception when no appropriate method is defined.
1073
Georg Brandl85eb8c12007-08-31 16:33:38 +00001074.. XXX above translation is not correct for new-style classes!
1075
Georg Brandl116aa622007-08-15 14:28:22 +00001076When implementing a class that emulates any built-in type, it is important that
1077the emulation only be implemented to the degree that it makes sense for the
1078object being modelled. For example, some sequences may work well with retrieval
1079of individual elements, but extracting a slice may not make sense. (One example
1080of this is the :class:`NodeList` interface in the W3C's Document Object Model.)
1081
1082
1083.. _customization:
1084
1085Basic customization
1086-------------------
1087
1088
1089.. method:: object.__new__(cls[, ...])
1090
1091 Called to create a new instance of class *cls*. :meth:`__new__` is a static
1092 method (special-cased so you need not declare it as such) that takes the class
1093 of which an instance was requested as its first argument. The remaining
1094 arguments are those passed to the object constructor expression (the call to the
1095 class). The return value of :meth:`__new__` should be the new object instance
1096 (usually an instance of *cls*).
1097
1098 Typical implementations create a new instance of the class by invoking the
1099 superclass's :meth:`__new__` method using ``super(currentclass,
1100 cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
1101 newly-created instance as necessary before returning it.
1102
1103 If :meth:`__new__` returns an instance of *cls*, then the new instance's
1104 :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
1105 *self* is the new instance and the remaining arguments are the same as were
1106 passed to :meth:`__new__`.
1107
1108 If :meth:`__new__` does not return an instance of *cls*, then the new instance's
1109 :meth:`__init__` method will not be invoked.
1110
1111 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
1112 int, str, or tuple) to customize instance creation.
1113
1114
1115.. method:: object.__init__(self[, ...])
1116
1117 .. index:: pair: class; constructor
1118
1119 Called when the instance is created. The arguments are those passed to the
1120 class constructor expression. If a base class has an :meth:`__init__` method,
1121 the derived class's :meth:`__init__` method, if any, must explicitly call it to
1122 ensure proper initialization of the base class part of the instance; for
1123 example: ``BaseClass.__init__(self, [args...])``. As a special constraint on
1124 constructors, no value may be returned; doing so will cause a :exc:`TypeError`
1125 to be raised at runtime.
1126
1127
1128.. method:: object.__del__(self)
1129
1130 .. index::
1131 single: destructor
1132 statement: del
1133
1134 Called when the instance is about to be destroyed. This is also called a
1135 destructor. If a base class has a :meth:`__del__` method, the derived class's
1136 :meth:`__del__` method, if any, must explicitly call it to ensure proper
1137 deletion of the base class part of the instance. Note that it is possible
1138 (though not recommended!) for the :meth:`__del__` method to postpone destruction
1139 of the instance by creating a new reference to it. It may then be called at a
1140 later time when this new reference is deleted. It is not guaranteed that
1141 :meth:`__del__` methods are called for objects that still exist when the
1142 interpreter exits.
1143
1144 .. note::
1145
1146 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
1147 the reference count for ``x`` by one, and the latter is only called when
1148 ``x``'s reference count reaches zero. Some common situations that may
1149 prevent the reference count of an object from going to zero include:
1150 circular references between objects (e.g., a doubly-linked list or a tree
1151 data structure with parent and child pointers); a reference to the object
1152 on the stack frame of a function that caught an exception (the traceback
1153 stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a
1154 reference to the object on the stack frame that raised an unhandled
1155 exception in interactive mode (the traceback stored in
1156 ``sys.last_traceback`` keeps the stack frame alive). The first situation
1157 can only be remedied by explicitly breaking the cycles; the latter two
1158 situations can be resolved by storing ``None`` in ``sys.last_traceback``.
1159 Circular references which are garbage are detected when the option cycle
1160 detector is enabled (it's on by default), but can only be cleaned up if
1161 there are no Python- level :meth:`__del__` methods involved. Refer to the
1162 documentation for the :mod:`gc` module for more information about how
1163 :meth:`__del__` methods are handled by the cycle detector, particularly
1164 the description of the ``garbage`` value.
1165
1166 .. warning::
1167
1168 Due to the precarious circumstances under which :meth:`__del__` methods are
1169 invoked, exceptions that occur during their execution are ignored, and a warning
1170 is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in
1171 response to a module being deleted (e.g., when execution of the program is
1172 done), other globals referenced by the :meth:`__del__` method may already have
1173 been deleted. For this reason, :meth:`__del__` methods should do the absolute
1174 minimum needed to maintain external invariants. Starting with version 1.5,
1175 Python guarantees that globals whose name begins with a single underscore are
1176 deleted from their module before other globals are deleted; if no other
1177 references to such globals exist, this may help in assuring that imported
1178 modules are still available at the time when the :meth:`__del__` method is
1179 called.
1180
1181
1182.. method:: object.__repr__(self)
1183
1184 .. index:: builtin: repr
1185
1186 Called by the :func:`repr` built-in function and by string conversions (reverse
1187 quotes) to compute the "official" string representation of an object. If at all
1188 possible, this should look like a valid Python expression that could be used to
1189 recreate an object with the same value (given an appropriate environment). If
1190 this is not possible, a string of the form ``<...some useful description...>``
1191 should be returned. The return value must be a string object. If a class
1192 defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also
1193 used when an "informal" string representation of instances of that class is
1194 required.
1195
Georg Brandl116aa622007-08-15 14:28:22 +00001196 This is typically used for debugging, so it is important that the representation
1197 is information-rich and unambiguous.
1198
1199
1200.. method:: object.__str__(self)
1201
1202 .. index::
1203 builtin: str
Georg Brandl4b491312007-08-31 09:22:56 +00001204 builtin: print
Georg Brandl116aa622007-08-15 14:28:22 +00001205
Georg Brandldcc56f82007-08-31 16:41:12 +00001206 Called by the :func:`str` built-in function and by the :func:`print` function
1207 to compute the "informal" string representation of an object. This differs
1208 from :meth:`__repr__` in that it does not have to be a valid Python
Georg Brandl116aa622007-08-15 14:28:22 +00001209 expression: a more convenient or concise representation may be used instead.
1210 The return value must be a string object.
1211
Georg Brandldcc56f82007-08-31 16:41:12 +00001212 .. XXX what about subclasses of string?
1213
Georg Brandl116aa622007-08-15 14:28:22 +00001214
Georg Brandl4b491312007-08-31 09:22:56 +00001215.. method:: object.__format__(self, format_spec)
1216
1217 .. index::
1218 pair: string; conversion
1219 builtin: str
1220 builtin: print
1221
1222 Called by the :func:`format` built-in function (and by extension, the
1223 :meth:`format` method of class :class:`str`) to produce a "formatted"
1224 string representation of an object. The ``format_spec`` argument is
1225 a string that contains a description of the formatting options desired.
1226 The interpretation of the ``format_spec`` argument is up to the type
1227 implementing :meth:`__format__`, however most classes will either
1228 delegate formatting to one of the built-in types, or use a similar
1229 formatting option syntax.
1230
1231 See :ref:`formatspec` for a description of the standard formatting syntax.
1232
1233 The return value must be a string object.
1234
1235
Georg Brandl116aa622007-08-15 14:28:22 +00001236.. method:: object.__lt__(self, other)
1237 object.__le__(self, other)
1238 object.__eq__(self, other)
1239 object.__ne__(self, other)
1240 object.__gt__(self, other)
1241 object.__ge__(self, other)
1242
1243 .. versionadded:: 2.1
1244
1245 These are the so-called "rich comparison" methods, and are called for comparison
1246 operators in preference to :meth:`__cmp__` below. The correspondence between
1247 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
1248 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls
1249 ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
1250 ``x.__ge__(y)``.
1251
1252 A rich comparison method may return the singleton ``NotImplemented`` if it does
1253 not implement the operation for a given pair of arguments. By convention,
1254 ``False`` and ``True`` are returned for a successful comparison. However, these
1255 methods can return any value, so if the comparison operator is used in a Boolean
1256 context (e.g., in the condition of an ``if`` statement), Python will call
1257 :func:`bool` on the value to determine if the result is true or false.
1258
1259 There are no implied relationships among the comparison operators. The truth of
1260 ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when defining
1261 :meth:`__eq__`, one should also define :meth:`__ne__` so that the operators will
1262 behave as expected.
1263
1264 There are no reflected (swapped-argument) versions of these methods (to be used
1265 when the left argument does not support the operation but the right argument
1266 does); rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
1267 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
1268 :meth:`__eq__` and :meth:`__ne__` are their own reflection.
1269
1270 Arguments to rich comparison methods are never coerced.
1271
1272
1273.. method:: object.__cmp__(self, other)
1274
1275 .. index::
1276 builtin: cmp
1277 single: comparisons
1278
1279 Called by comparison operations if rich comparison (see above) is not defined.
1280 Should return a negative integer if ``self < other``, zero if ``self == other``,
1281 a positive integer if ``self > other``. If no :meth:`__cmp__`, :meth:`__eq__`
1282 or :meth:`__ne__` operation is defined, class instances are compared by object
1283 identity ("address"). See also the description of :meth:`__hash__` for some
1284 important notes on creating objects which support custom comparison operations
1285 and are usable as dictionary keys. (Note: the restriction that exceptions are
1286 not propagated by :meth:`__cmp__` has been removed since Python 1.5.)
1287
1288
1289.. method:: object.__rcmp__(self, other)
1290
1291 .. versionchanged:: 2.1
1292 No longer supported.
1293
1294
1295.. method:: object.__hash__(self)
1296
1297 .. index::
1298 object: dictionary
1299 builtin: hash
1300
1301 Called for the key object for dictionary operations, and by the built-in
1302 function :func:`hash`. Should return a 32-bit integer usable as a hash value
1303 for dictionary operations. The only required property is that objects which
1304 compare equal have the same hash value; it is advised to somehow mix together
1305 (e.g., using exclusive or) the hash values for the components of the object that
1306 also play a part in comparison of objects. If a class does not define a
1307 :meth:`__cmp__` method it should not define a :meth:`__hash__` operation either;
1308 if it defines :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its
1309 instances will not be usable as dictionary keys. If a class defines mutable
1310 objects and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
1311 implement :meth:`__hash__`, since the dictionary implementation requires that a
1312 key's hash value is immutable (if the object's hash value changes, it will be in
1313 the wrong hash bucket).
1314
1315 .. versionchanged:: 2.5
1316 :meth:`__hash__` may now also return a long integer object; the 32-bit integer
1317 is then derived from the hash of that object.
1318
1319 .. index:: single: __cmp__() (object method)
1320
1321
1322.. method:: object.__bool__(self)
1323
1324 .. index:: single: __len__() (mapping object method)
1325
1326 Called to implement truth value testing, and the built-in operation ``bool()``;
1327 should return ``False`` or ``True``. When this method is not defined,
1328 :meth:`__len__` is called, if it is defined (see below) and ``True`` is returned
1329 when the length is not zero. If a class defines neither :meth:`__len__` nor
1330 :meth:`__bool__`, all its instances are considered true.
1331
1332
Georg Brandl116aa622007-08-15 14:28:22 +00001333.. _attribute-access:
1334
1335Customizing attribute access
1336----------------------------
1337
1338The following methods can be defined to customize the meaning of attribute
1339access (use of, assignment to, or deletion of ``x.name``) for class instances.
1340
Georg Brandl85eb8c12007-08-31 16:33:38 +00001341.. XXX explain how descriptors interfere here!
1342
Georg Brandl116aa622007-08-15 14:28:22 +00001343
1344.. method:: object.__getattr__(self, name)
1345
1346 Called when an attribute lookup has not found the attribute in the usual places
1347 (i.e. it is not an instance attribute nor is it found in the class tree for
1348 ``self``). ``name`` is the attribute name. This method should return the
1349 (computed) attribute value or raise an :exc:`AttributeError` exception.
1350
Georg Brandl116aa622007-08-15 14:28:22 +00001351 Note that if the attribute is found through the normal mechanism,
1352 :meth:`__getattr__` is not called. (This is an intentional asymmetry between
1353 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
1354 reasons and because otherwise :meth:`__setattr__` would have no way to access
1355 other attributes of the instance. Note that at least for instance variables,
1356 you can fake total control by not inserting any values in the instance attribute
1357 dictionary (but instead inserting them in another object). See the
Georg Brandl85eb8c12007-08-31 16:33:38 +00001358 :meth:`__getattribute__` method below for a way to actually get total control
1359 over attribute access.
Georg Brandl116aa622007-08-15 14:28:22 +00001360
1361
1362.. method:: object.__getattribute__(self, name)
1363
1364 Called unconditionally to implement attribute accesses for instances of the
1365 class. If the class also defines :meth:`__getattr__`, the latter will not be
1366 called unless :meth:`__getattribute__` either calls it explicitly or raises an
1367 :exc:`AttributeError`. This method should return the (computed) attribute value
1368 or raise an :exc:`AttributeError` exception. In order to avoid infinite
1369 recursion in this method, its implementation should always call the base class
1370 method with the same name to access any attributes it needs, for example,
1371 ``object.__getattribute__(self, name)``.
1372
1373
Georg Brandl85eb8c12007-08-31 16:33:38 +00001374.. method:: object.__setattr__(self, name, value)
1375
1376 Called when an attribute assignment is attempted. This is called instead of
1377 the normal mechanism (i.e. store the value in the instance dictionary).
1378 *name* is the attribute name, *value* is the value to be assigned to it.
1379
1380 If :meth:`__setattr__` wants to assign to an instance attribute, it should
1381 call the base class method with the same name, for example,
1382 ``object.__setattr__(self, name, value)``.
1383
1384
1385.. method:: object.__delattr__(self, name)
1386
1387 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
1388 should only be implemented if ``del obj.name`` is meaningful for the object.
1389
1390
Georg Brandl116aa622007-08-15 14:28:22 +00001391.. _descriptors:
1392
1393Implementing Descriptors
1394^^^^^^^^^^^^^^^^^^^^^^^^
1395
1396The following methods only apply when an instance of the class containing the
1397method (a so-called *descriptor* class) appears in the class dictionary of
Georg Brandl85eb8c12007-08-31 16:33:38 +00001398another class, known as the *owner* class. In the examples below, "the
Georg Brandl116aa622007-08-15 14:28:22 +00001399attribute" refers to the attribute whose name is the key of the property in the
Georg Brandl85eb8c12007-08-31 16:33:38 +00001400owner class' :attr:`__dict__`.
Georg Brandl116aa622007-08-15 14:28:22 +00001401
1402
1403.. method:: object.__get__(self, instance, owner)
1404
1405 Called to get the attribute of the owner class (class attribute access) or of an
1406 instance of that class (instance attribute access). *owner* is always the owner
1407 class, while *instance* is the instance that the attribute was accessed through,
1408 or ``None`` when the attribute is accessed through the *owner*. This method
1409 should return the (computed) attribute value or raise an :exc:`AttributeError`
1410 exception.
1411
1412
1413.. method:: object.__set__(self, instance, value)
1414
1415 Called to set the attribute on an instance *instance* of the owner class to a
1416 new value, *value*.
1417
1418
1419.. method:: object.__delete__(self, instance)
1420
1421 Called to delete the attribute on an instance *instance* of the owner class.
1422
1423
1424.. _descriptor-invocation:
1425
1426Invoking Descriptors
1427^^^^^^^^^^^^^^^^^^^^
1428
1429In general, a descriptor is an object attribute with "binding behavior", one
1430whose attribute access has been overridden by methods in the descriptor
1431protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
1432those methods are defined for an object, it is said to be a descriptor.
1433
1434The default behavior for attribute access is to get, set, or delete the
1435attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
1436starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
1437continuing through the base classes of ``type(a)`` excluding metaclasses.
1438
1439However, if the looked-up value is an object defining one of the descriptor
1440methods, then Python may override the default behavior and invoke the descriptor
1441method instead. Where this occurs in the precedence chain depends on which
1442descriptor methods were defined and how they were called. Note that descriptors
1443are only invoked for new style objects or classes (ones that subclass
1444:class:`object()` or :class:`type()`).
1445
1446The starting point for descriptor invocation is a binding, ``a.x``. How the
1447arguments are assembled depends on ``a``:
1448
1449Direct Call
1450 The simplest and least common call is when user code directly invokes a
1451 descriptor method: ``x.__get__(a)``.
1452
1453Instance Binding
Georg Brandl85eb8c12007-08-31 16:33:38 +00001454 If binding to an object instance, ``a.x`` is transformed into the call:
Georg Brandl116aa622007-08-15 14:28:22 +00001455 ``type(a).__dict__['x'].__get__(a, type(a))``.
1456
1457Class Binding
Georg Brandl85eb8c12007-08-31 16:33:38 +00001458 If binding to a class, ``A.x`` is transformed into the call:
Georg Brandl116aa622007-08-15 14:28:22 +00001459 ``A.__dict__['x'].__get__(None, A)``.
1460
1461Super Binding
1462 If ``a`` is an instance of :class:`super`, then the binding ``super(B,
1463 obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
1464 immediately preceding ``B`` and then invokes the descriptor with the call:
1465 ``A.__dict__['m'].__get__(obj, A)``.
1466
1467For instance bindings, the precedence of descriptor invocation depends on the
Guido van Rossum04110fb2007-08-24 16:32:05 +00001468which descriptor methods are defined. Normally, data descriptors define both
1469:meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the
Georg Brandl116aa622007-08-15 14:28:22 +00001470:meth:`__get__` method. Data descriptors always override a redefinition in an
1471instance dictionary. In contrast, non-data descriptors can be overridden by
Guido van Rossum04110fb2007-08-24 16:32:05 +00001472instances. [#]_
Georg Brandl116aa622007-08-15 14:28:22 +00001473
1474Python methods (including :func:`staticmethod` and :func:`classmethod`) are
1475implemented as non-data descriptors. Accordingly, instances can redefine and
1476override methods. This allows individual instances to acquire behaviors that
1477differ from other instances of the same class.
1478
1479The :func:`property` function is implemented as a data descriptor. Accordingly,
1480instances cannot override the behavior of a property.
1481
1482
1483.. _slots:
1484
1485__slots__
1486^^^^^^^^^
1487
Georg Brandl85eb8c12007-08-31 16:33:38 +00001488By default, instances of classes have a dictionary for attribute storage. This
1489wastes space for objects having very few instance variables. The space
1490consumption can become acute when creating large numbers of instances.
Georg Brandl116aa622007-08-15 14:28:22 +00001491
Georg Brandl85eb8c12007-08-31 16:33:38 +00001492The default can be overridden by defining *__slots__* in a class definition.
1493The *__slots__* declaration takes a sequence of instance variables and reserves
1494just enough space in each instance to hold a value for each variable. Space is
1495saved because *__dict__* is not created for each instance.
Georg Brandl116aa622007-08-15 14:28:22 +00001496
1497
Georg Brandl85eb8c12007-08-31 16:33:38 +00001498.. data:: object.__slots__
Georg Brandl116aa622007-08-15 14:28:22 +00001499
Georg Brandl85eb8c12007-08-31 16:33:38 +00001500 This class variable can be assigned a string, iterable, or sequence of
1501 strings with variable names used by instances. If defined in a new-style
1502 class, *__slots__* reserves space for the declared variables and prevents the
1503 automatic creation of *__dict__* and *__weakref__* for each instance.
Georg Brandl116aa622007-08-15 14:28:22 +00001504
1505 .. versionadded:: 2.2
1506
1507Notes on using *__slots__*
1508
1509* Without a *__dict__* variable, instances cannot be assigned new variables not
1510 listed in the *__slots__* definition. Attempts to assign to an unlisted
1511 variable name raises :exc:`AttributeError`. If dynamic assignment of new
Georg Brandl85eb8c12007-08-31 16:33:38 +00001512 variables is desired, then add ``'__dict__'`` to the sequence of strings in
1513 the *__slots__* declaration.
Georg Brandl116aa622007-08-15 14:28:22 +00001514
1515 .. versionchanged:: 2.3
1516 Previously, adding ``'__dict__'`` to the *__slots__* declaration would not
1517 enable the assignment of new attributes not specifically listed in the sequence
1518 of instance variable names.
1519
1520* Without a *__weakref__* variable for each instance, classes defining
1521 *__slots__* do not support weak references to its instances. If weak reference
1522 support is needed, then add ``'__weakref__'`` to the sequence of strings in the
1523 *__slots__* declaration.
1524
1525 .. versionchanged:: 2.3
1526 Previously, adding ``'__weakref__'`` to the *__slots__* declaration would not
1527 enable support for weak references.
1528
1529* *__slots__* are implemented at the class level by creating descriptors
1530 (:ref:`descriptors`) for each variable name. As a result, class attributes
1531 cannot be used to set default values for instance variables defined by
1532 *__slots__*; otherwise, the class attribute would overwrite the descriptor
1533 assignment.
1534
1535* If a class defines a slot also defined in a base class, the instance variable
1536 defined by the base class slot is inaccessible (except by retrieving its
1537 descriptor directly from the base class). This renders the meaning of the
1538 program undefined. In the future, a check may be added to prevent this.
1539
1540* The action of a *__slots__* declaration is limited to the class where it is
1541 defined. As a result, subclasses will have a *__dict__* unless they also define
1542 *__slots__*.
1543
1544* *__slots__* do not work for classes derived from "variable-length" built-in
1545 types such as :class:`long`, :class:`str` and :class:`tuple`.
1546
1547* Any non-string iterable may be assigned to *__slots__*. Mappings may also be
1548 used; however, in the future, special meaning may be assigned to the values
1549 corresponding to each key.
1550
1551* *__class__* assignment works only if both classes have the same *__slots__*.
1552
1553 .. versionchanged:: 2.6
1554 Previously, *__class__* assignment raised an error if either new or old class
1555 had *__slots__*.
1556
1557
1558.. _metaclasses:
1559
1560Customizing class creation
1561--------------------------
1562
Georg Brandl85eb8c12007-08-31 16:33:38 +00001563By default, classes are constructed using :func:`type`. A class definition is
1564read into a separate namespace and the value of class name is bound to the
1565result of ``type(name, bases, dict)``.
Georg Brandl116aa622007-08-15 14:28:22 +00001566
1567When the class definition is read, if *__metaclass__* is defined then the
1568callable assigned to it will be called instead of :func:`type`. The allows
1569classes or functions to be written which monitor or alter the class creation
1570process:
1571
1572* Modifying the class dictionary prior to the class being created.
1573
1574* Returning an instance of another class -- essentially performing the role of a
1575 factory function.
1576
Georg Brandl85eb8c12007-08-31 16:33:38 +00001577.. XXX needs to be updated for the "new metaclasses" PEP
Georg Brandl116aa622007-08-15 14:28:22 +00001578.. data:: __metaclass__
1579
1580 This variable can be any callable accepting arguments for ``name``, ``bases``,
1581 and ``dict``. Upon class creation, the callable is used instead of the built-in
1582 :func:`type`.
1583
1584 .. versionadded:: 2.2
1585
1586The appropriate metaclass is determined by the following precedence rules:
1587
1588* If ``dict['__metaclass__']`` exists, it is used.
1589
1590* Otherwise, if there is at least one base class, its metaclass is used (this
1591 looks for a *__class__* attribute first and if not found, uses its type).
1592
1593* Otherwise, if a global variable named __metaclass__ exists, it is used.
1594
Georg Brandl85eb8c12007-08-31 16:33:38 +00001595* Otherwise, the default metaclass (:class:`type`) is used.
Georg Brandl116aa622007-08-15 14:28:22 +00001596
1597The potential uses for metaclasses are boundless. Some ideas that have been
1598explored including logging, interface checking, automatic delegation, automatic
1599property creation, proxies, frameworks, and automatic resource
1600locking/synchronization.
1601
1602
1603.. _callable-types:
1604
1605Emulating callable objects
1606--------------------------
1607
1608
1609.. method:: object.__call__(self[, args...])
1610
1611 .. index:: pair: call; instance
1612
1613 Called when the instance is "called" as a function; if this method is defined,
1614 ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
1615
1616
1617.. _sequence-types:
1618
1619Emulating container types
1620-------------------------
1621
1622The following methods can be defined to implement container objects. Containers
1623usually are sequences (such as lists or tuples) or mappings (like dictionaries),
1624but can represent other containers as well. The first set of methods is used
1625either to emulate a sequence or to emulate a mapping; the difference is that for
1626a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
1627N`` where *N* is the length of the sequence, or slice objects, which define a
1628range of items. (For backwards compatibility, the method :meth:`__getslice__`
1629(see below) can also be defined to handle simple, but not extended slices.) It
1630is also recommended that mappings provide the methods :meth:`keys`,
1631:meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`,
1632:meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`,
1633:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar
1634to those for Python's standard dictionary objects. The :mod:`UserDict` module
1635provides a :class:`DictMixin` class to help create those methods from a base set
1636of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and
1637:meth:`keys`. Mutable sequences should provide methods :meth:`append`,
1638:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`,
1639:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list
1640objects. Finally, sequence types should implement addition (meaning
1641concatenation) and multiplication (meaning repetition) by defining the methods
1642:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`,
1643:meth:`__rmul__` and :meth:`__imul__` described below; they should not define
1644other numerical operators. It is recommended that both mappings and sequences
1645implement the :meth:`__contains__` method to allow efficient use of the ``in``
1646operator; for mappings, ``in`` should be equivalent of :meth:`has_key`; for
1647sequences, it should search through the values. It is further recommended that
1648both mappings and sequences implement the :meth:`__iter__` method to allow
1649efficient iteration through the container; for mappings, :meth:`__iter__` should
1650be the same as :meth:`iterkeys`; for sequences, it should iterate through the
1651values.
1652
1653
1654.. method:: object.__len__(self)
1655
1656 .. index::
1657 builtin: len
1658 single: __bool__() (object method)
1659
1660 Called to implement the built-in function :func:`len`. Should return the length
1661 of the object, an integer ``>=`` 0. Also, an object that doesn't define a
1662 :meth:`__bool__` method and whose :meth:`__len__` method returns zero is
1663 considered to be false in a Boolean context.
1664
1665
1666.. method:: object.__getitem__(self, key)
1667
1668 .. index:: object: slice
1669
1670 Called to implement evaluation of ``self[key]``. For sequence types, the
1671 accepted keys should be integers and slice objects. Note that the special
1672 interpretation of negative indexes (if the class wishes to emulate a sequence
1673 type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
1674 type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
1675 for the sequence (after any special interpretation of negative values),
1676 :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
1677 in the container), :exc:`KeyError` should be raised.
1678
1679 .. note::
1680
1681 :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
1682 indexes to allow proper detection of the end of the sequence.
1683
1684
1685.. method:: object.__setitem__(self, key, value)
1686
1687 Called to implement assignment to ``self[key]``. Same note as for
1688 :meth:`__getitem__`. This should only be implemented for mappings if the
1689 objects support changes to the values for keys, or if new keys can be added, or
1690 for sequences if elements can be replaced. The same exceptions should be raised
1691 for improper *key* values as for the :meth:`__getitem__` method.
1692
1693
1694.. method:: object.__delitem__(self, key)
1695
1696 Called to implement deletion of ``self[key]``. Same note as for
1697 :meth:`__getitem__`. This should only be implemented for mappings if the
1698 objects support removal of keys, or for sequences if elements can be removed
1699 from the sequence. The same exceptions should be raised for improper *key*
1700 values as for the :meth:`__getitem__` method.
1701
1702
1703.. method:: object.__iter__(self)
1704
1705 This method is called when an iterator is required for a container. This method
1706 should return a new iterator object that can iterate over all the objects in the
1707 container. For mappings, it should iterate over the keys of the container, and
1708 should also be made available as the method :meth:`iterkeys`.
1709
1710 Iterator objects also need to implement this method; they are required to return
1711 themselves. For more information on iterator objects, see :ref:`typeiter`.
1712
1713The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
1714implemented as an iteration through a sequence. However, container objects can
1715supply the following special method with a more efficient implementation, which
1716also does not require the object be a sequence.
1717
1718
1719.. method:: object.__contains__(self, item)
1720
1721 Called to implement membership test operators. Should return true if *item* is
1722 in *self*, false otherwise. For mapping objects, this should consider the keys
1723 of the mapping rather than the values or the key-item pairs.
1724
1725
1726.. _sequence-methods:
1727
1728Additional methods for emulation of sequence types
1729--------------------------------------------------
1730
1731The following optional methods can be defined to further emulate sequence
1732objects. Immutable sequences methods should at most only define
1733:meth:`__getslice__`; mutable sequences might define all three methods.
1734
1735
1736.. method:: object.__getslice__(self, i, j)
1737
1738 .. deprecated:: 2.0
1739 Support slice objects as parameters to the :meth:`__getitem__` method.
Guido van Rossum04110fb2007-08-24 16:32:05 +00001740 (However, built-in types in CPython currently still implement
1741 :meth:`__getslice__`. Therefore, you have to override it in derived
1742 classes when implementing slicing.)
Georg Brandl116aa622007-08-15 14:28:22 +00001743
1744 Called to implement evaluation of ``self[i:j]``. The returned object should be
1745 of the same type as *self*. Note that missing *i* or *j* in the slice
1746 expression are replaced by zero or ``sys.maxint``, respectively. If negative
1747 indexes are used in the slice, the length of the sequence is added to that
1748 index. If the instance does not implement the :meth:`__len__` method, an
1749 :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this
1750 way are not still negative. Indexes which are greater than the length of the
1751 sequence are not modified. If no :meth:`__getslice__` is found, a slice object
1752 is created instead, and passed to :meth:`__getitem__` instead.
1753
1754
1755.. method:: object.__setslice__(self, i, j, sequence)
1756
1757 Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as
1758 for :meth:`__getslice__`.
1759
1760 This method is deprecated. If no :meth:`__setslice__` is found, or for extended
1761 slicing of the form ``self[i:j:k]``, a slice object is created, and passed to
1762 :meth:`__setitem__`, instead of :meth:`__setslice__` being called.
1763
1764
1765.. method:: object.__delslice__(self, i, j)
1766
1767 Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for
1768 :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is
1769 found, or for extended slicing of the form ``self[i:j:k]``, a slice object is
1770 created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__`
1771 being called.
1772
1773Notice that these methods are only invoked when a single slice with a single
1774colon is used, and the slice method is available. For slice operations
1775involving extended slice notation, or in absence of the slice methods,
1776:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a
1777slice object as argument.
1778
1779The following example demonstrate how to make your program or module compatible
1780with earlier versions of Python (assuming that methods :meth:`__getitem__`,
1781:meth:`__setitem__` and :meth:`__delitem__` support slice objects as
1782arguments)::
1783
1784 class MyClass:
1785 ...
1786 def __getitem__(self, index):
1787 ...
1788 def __setitem__(self, index, value):
1789 ...
1790 def __delitem__(self, index):
1791 ...
1792
1793 if sys.version_info < (2, 0):
1794 # They won't be defined if version is at least 2.0 final
1795
1796 def __getslice__(self, i, j):
1797 return self[max(0, i):max(0, j):]
1798 def __setslice__(self, i, j, seq):
1799 self[max(0, i):max(0, j):] = seq
1800 def __delslice__(self, i, j):
1801 del self[max(0, i):max(0, j):]
1802 ...
1803
1804Note the calls to :func:`max`; these are necessary because of the handling of
1805negative indices before the :meth:`__\*slice__` methods are called. When
1806negative indexes are used, the :meth:`__\*item__` methods receive them as
1807provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index
1808values. For each negative index value, the length of the sequence is added to
1809the index before calling the method (which may still result in a negative
1810index); this is the customary handling of negative indexes by the built-in
1811sequence types, and the :meth:`__\*item__` methods are expected to do this as
1812well. However, since they should already be doing that, negative indexes cannot
1813be passed in; they must be constrained to the bounds of the sequence before
1814being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)``
1815conveniently returns the proper value.
1816
1817
1818.. _numeric-types:
1819
1820Emulating numeric types
1821-----------------------
1822
1823The following methods can be defined to emulate numeric objects. Methods
1824corresponding to operations that are not supported by the particular kind of
1825number implemented (e.g., bitwise operations for non-integral numbers) should be
1826left undefined.
1827
1828
1829.. method:: object.__add__(self, other)
1830 object.__sub__(self, other)
1831 object.__mul__(self, other)
1832 object.__floordiv__(self, other)
1833 object.__mod__(self, other)
1834 object.__divmod__(self, other)
1835 object.__pow__(self, other[, modulo])
1836 object.__lshift__(self, other)
1837 object.__rshift__(self, other)
1838 object.__and__(self, other)
1839 object.__xor__(self, other)
1840 object.__or__(self, other)
1841
1842 .. index::
1843 builtin: divmod
1844 builtin: pow
1845 builtin: pow
1846
1847 These methods are called to implement the binary arithmetic operations (``+``,
1848 ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
1849 ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression
1850 *x*``+``*y*, where *x* is an instance of a class that has an :meth:`__add__`
1851 method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the
1852 equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
1853 related to :meth:`__truediv__` (described below). Note that :meth:`__pow__`
1854 should be defined to accept an optional third argument if the ternary version of
1855 the built-in :func:`pow` function is to be supported.
1856
1857 If one of those methods does not support the operation with the supplied
1858 arguments, it should return ``NotImplemented``.
1859
1860
1861.. method:: object.__div__(self, other)
1862 object.__truediv__(self, other)
1863
1864 The division operator (``/``) is implemented by these methods. The
1865 :meth:`__truediv__` method is used when ``__future__.division`` is in effect,
1866 otherwise :meth:`__div__` is used. If only one of these two methods is defined,
1867 the object will not support division in the alternate context; :exc:`TypeError`
1868 will be raised instead.
1869
1870
1871.. method:: object.__radd__(self, other)
1872 object.__rsub__(self, other)
1873 object.__rmul__(self, other)
1874 object.__rdiv__(self, other)
1875 object.__rtruediv__(self, other)
1876 object.__rfloordiv__(self, other)
1877 object.__rmod__(self, other)
1878 object.__rdivmod__(self, other)
1879 object.__rpow__(self, other)
1880 object.__rlshift__(self, other)
1881 object.__rrshift__(self, other)
1882 object.__rand__(self, other)
1883 object.__rxor__(self, other)
1884 object.__ror__(self, other)
1885
1886 .. index::
1887 builtin: divmod
1888 builtin: pow
1889
1890 These methods are called to implement the binary arithmetic operations (``+``,
1891 ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``,
1892 ``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are
1893 only called if the left operand does not support the corresponding operation and
1894 the operands are of different types. [#]_ For instance, to evaluate the
1895 expression *x*``-``*y*, where *y* is an instance of a class that has an
1896 :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns
1897 *NotImplemented*.
1898
1899 .. index:: builtin: pow
1900
1901 Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
1902 coercion rules would become too complicated).
1903
1904 .. note::
1905
1906 If the right operand's type is a subclass of the left operand's type and that
1907 subclass provides the reflected method for the operation, this method will be
1908 called before the left operand's non-reflected method. This behavior allows
1909 subclasses to override their ancestors' operations.
1910
1911
1912.. method:: object.__iadd__(self, other)
1913 object.__isub__(self, other)
1914 object.__imul__(self, other)
1915 object.__idiv__(self, other)
1916 object.__itruediv__(self, other)
1917 object.__ifloordiv__(self, other)
1918 object.__imod__(self, other)
1919 object.__ipow__(self, other[, modulo])
1920 object.__ilshift__(self, other)
1921 object.__irshift__(self, other)
1922 object.__iand__(self, other)
1923 object.__ixor__(self, other)
1924 object.__ior__(self, other)
1925
1926 These methods are called to implement the augmented arithmetic operations
1927 (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
1928 ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
1929 in-place (modifying *self*) and return the result (which could be, but does
1930 not have to be, *self*). If a specific method is not defined, the augmented
1931 operation falls back to the normal methods. For instance, to evaluate the
1932 expression *x*``+=``*y*, where *x* is an instance of a class that has an
1933 :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance
1934 of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
1935 and ``y.__radd__(x)`` are considered, as with the evaluation of *x*``+``*y*.
1936
1937
1938.. method:: object.__neg__(self)
1939 object.__pos__(self)
1940 object.__abs__(self)
1941 object.__invert__(self)
1942
1943 .. index:: builtin: abs
1944
1945 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
1946 and ``~``).
1947
1948
1949.. method:: object.__complex__(self)
1950 object.__int__(self)
1951 object.__long__(self)
1952 object.__float__(self)
1953
1954 .. index::
1955 builtin: complex
1956 builtin: int
1957 builtin: long
1958 builtin: float
1959
1960 Called to implement the built-in functions :func:`complex`, :func:`int`,
1961 :func:`long`, and :func:`float`. Should return a value of the appropriate type.
1962
1963
1964.. method:: object.__index__(self)
1965
1966 Called to implement :func:`operator.index`. Also called whenever Python needs
1967 an integer object (such as in slicing, or in the built-in :func:`bin`,
1968 :func:`hex` and :func:`oct` functions). Must return an integer (int or long).
1969
1970 .. versionadded:: 2.5
1971
1972
1973.. _context-managers:
1974
1975With Statement Context Managers
1976-------------------------------
1977
1978.. versionadded:: 2.5
1979
1980A :dfn:`context manager` is an object that defines the runtime context to be
1981established when executing a :keyword:`with` statement. The context manager
1982handles the entry into, and the exit from, the desired runtime context for the
1983execution of the block of code. Context managers are normally invoked using the
1984:keyword:`with` statement (described in section :ref:`with`), but can also be
1985used by directly invoking their methods.
1986
1987.. index::
1988 statement: with
1989 single: context manager
1990
1991Typical uses of context managers include saving and restoring various kinds of
1992global state, locking and unlocking resources, closing opened files, etc.
1993
1994For more information on context managers, see :ref:`typecontextmanager`.
1995
1996
1997.. method:: object.__enter__(self)
1998
1999 Enter the runtime context related to this object. The :keyword:`with` statement
2000 will bind this method's return value to the target(s) specified in the
2001 :keyword:`as` clause of the statement, if any.
2002
2003
2004.. method:: object.__exit__(self, exc_type, exc_value, traceback)
2005
2006 Exit the runtime context related to this object. The parameters describe the
2007 exception that caused the context to be exited. If the context was exited
2008 without an exception, all three arguments will be :const:`None`.
2009
2010 If an exception is supplied, and the method wishes to suppress the exception
2011 (i.e., prevent it from being propagated), it should return a true value.
2012 Otherwise, the exception will be processed normally upon exit from this method.
2013
2014 Note that :meth:`__exit__` methods should not reraise the passed-in exception;
2015 this is the caller's responsibility.
2016
2017
2018.. seealso::
2019
2020 :pep:`0343` - The "with" statement
2021 The specification, background, and examples for the Python :keyword:`with`
2022 statement.
2023
2024.. rubric:: Footnotes
2025
Guido van Rossum04110fb2007-08-24 16:32:05 +00002026.. [#] A descriptor can define any combination of :meth:`__get__`,
2027 :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`,
2028 then accessing the attribute even on an instance will return the descriptor
2029 object itself. If the descriptor defines :meth:`__set__` and/or
2030 :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a
2031 non-data descriptor.
2032
Georg Brandl116aa622007-08-15 14:28:22 +00002033.. [#] For operands of the same type, it is assumed that if the non-reflected method
2034 (such as :meth:`__add__`) fails the operation is not supported, which is why the
2035 reflected method is not called.
2036