blob: dda18ba6ac31105427f5a70681079936c64e9aac [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
Nick Coghlan337b2bf2012-05-20 18:30:49 +100038:func:`id` function returns an integer representing its identity.
39
40.. impl-detail::
41
42 For CPython, ``id(x)`` is the memory address where ``x`` is stored.
43
Georg Brandl116aa622007-08-15 14:28:22 +000044An object's type determines the operations that the object supports (e.g., "does
45it have a length?") and also defines the possible values for objects of that
46type. The :func:`type` function returns an object's type (which is an object
Nick Coghlan337b2bf2012-05-20 18:30:49 +100047itself). Like its identity, an object's :dfn:`type` is also unchangeable.
48[#]_
49
50The *value* of some objects can change. Objects whose value can
Georg Brandl116aa622007-08-15 14:28:22 +000051change are said to be *mutable*; objects whose value is unchangeable once they
52are created are called *immutable*. (The value of an immutable container object
53that contains a reference to a mutable object can change when the latter's value
54is changed; however the container is still considered immutable, because the
55collection of objects it contains cannot be changed. So, immutability is not
56strictly the same as having an unchangeable value, it is more subtle.) An
57object's mutability is determined by its type; for instance, numbers, strings
58and tuples are immutable, while dictionaries and lists are mutable.
59
60.. index::
61 single: garbage collection
62 single: reference counting
63 single: unreachable object
64
65Objects are never explicitly destroyed; however, when they become unreachable
66they may be garbage-collected. An implementation is allowed to postpone garbage
67collection or omit it altogether --- it is a matter of implementation quality
68how garbage collection is implemented, as long as no objects are collected that
Georg Brandl495f7b52009-10-27 15:28:25 +000069are still reachable.
70
71.. impl-detail::
72
73 CPython currently uses a reference-counting scheme with (optional) delayed
74 detection of cyclically linked garbage, which collects most objects as soon
75 as they become unreachable, but is not guaranteed to collect garbage
76 containing circular references. See the documentation of the :mod:`gc`
77 module for information on controlling the collection of cyclic garbage.
78 Other implementations act differently and CPython may change.
Gregory P. Smithc5425472011-03-10 11:28:50 -080079 Do not depend on immediate finalization of objects when they become
Raymond Hettingeraa7886d2014-05-26 22:20:37 -070080 unreachable (so you should always close files explicitly).
Georg Brandl116aa622007-08-15 14:28:22 +000081
82Note that the use of the implementation's tracing or debugging facilities may
83keep objects alive that would normally be collectable. Also note that catching
84an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
85objects alive.
86
87Some objects contain references to "external" resources such as open files or
88windows. It is understood that these resources are freed when the object is
89garbage-collected, but since garbage collection is not guaranteed to happen,
90such objects also provide an explicit way to release the external resource,
91usually a :meth:`close` method. Programs are strongly recommended to explicitly
92close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement
Nick Coghlan3a5d7e32008-08-31 12:40:14 +000093and the ':keyword:`with`' statement provide convenient ways to do this.
Georg Brandl116aa622007-08-15 14:28:22 +000094
95.. index:: single: container
96
97Some objects contain references to other objects; these are called *containers*.
98Examples of containers are tuples, lists and dictionaries. The references are
99part of a container's value. In most cases, when we talk about the value of a
100container, we imply the values, not the identities of the contained objects;
101however, when we talk about the mutability of a container, only the identities
102of the immediately contained objects are implied. So, if an immutable container
103(like a tuple) contains a reference to a mutable object, its value changes if
104that mutable object is changed.
105
106Types affect almost all aspects of object behavior. Even the importance of
107object identity is affected in some sense: for immutable types, operations that
108compute new values may actually return a reference to any existing object with
109the same type and value, while for mutable objects this is not allowed. E.g.,
110after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
111with the value one, depending on the implementation, but after ``c = []; d =
112[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
113created empty lists. (Note that ``c = d = []`` assigns the same object to both
114``c`` and ``d``.)
115
116
117.. _types:
118
119The standard type hierarchy
120===========================
121
122.. index::
123 single: type
124 pair: data; type
125 pair: type; hierarchy
126 pair: extension; module
127 pair: C; language
128
129Below is a list of the types that are built into Python. Extension modules
130(written in C, Java, or other languages, depending on the implementation) can
131define additional types. Future versions of Python may add types to the type
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000132hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.),
133although such additions will often be provided via the standard library instead.
Georg Brandl116aa622007-08-15 14:28:22 +0000134
135.. index::
136 single: attribute
137 pair: special; attribute
138 triple: generic; special; attribute
139
140Some of the type descriptions below contain a paragraph listing 'special
141attributes.' These are attributes that provide access to the implementation and
142are not intended for general use. Their definition may change in the future.
143
144None
145 .. index:: object: None
146
147 This type has a single value. There is a single object with this value. This
148 object is accessed through the built-in name ``None``. It is used to signify the
149 absence of a value in many situations, e.g., it is returned from functions that
150 don't explicitly return anything. Its truth value is false.
151
152NotImplemented
153 .. index:: object: NotImplemented
154
155 This type has a single value. There is a single object with this value. This
156 object is accessed through the built-in name ``NotImplemented``. Numeric methods
Ethan Furmanb0049432014-11-26 21:15:35 -0800157 and rich comparison methods should return this value if they do not implement the
Georg Brandl116aa622007-08-15 14:28:22 +0000158 operation for the operands provided. (The interpreter will then try the
159 reflected operation, or some other fallback, depending on the operator.) Its
160 truth value is true.
161
Ethan Furmanb0049432014-11-26 21:15:35 -0800162 See
163 :ref:`implementing-the-arithmetic-operations`
164 for more details.
165
166
Georg Brandl116aa622007-08-15 14:28:22 +0000167Ellipsis
168 .. index:: object: Ellipsis
169
170 This type has a single value. There is a single object with this value. This
171 object is accessed through the literal ``...`` or the built-in name
172 ``Ellipsis``. Its truth value is true.
173
Christian Heimes072c0f12008-01-03 23:01:04 +0000174:class:`numbers.Number`
Georg Brandl116aa622007-08-15 14:28:22 +0000175 .. index:: object: numeric
176
177 These are created by numeric literals and returned as results by arithmetic
178 operators and arithmetic built-in functions. Numeric objects are immutable;
179 once created their value never changes. Python numbers are of course strongly
180 related to mathematical numbers, but subject to the limitations of numerical
181 representation in computers.
182
183 Python distinguishes between integers, floating point numbers, and complex
184 numbers:
185
Christian Heimes072c0f12008-01-03 23:01:04 +0000186 :class:`numbers.Integral`
Georg Brandl116aa622007-08-15 14:28:22 +0000187 .. index:: object: integer
188
189 These represent elements from the mathematical set of integers (positive and
190 negative).
191
Georg Brandl59d69162008-01-07 09:27:36 +0000192 There are two types of integers:
Georg Brandl116aa622007-08-15 14:28:22 +0000193
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000194 Integers (:class:`int`)
Georg Brandl116aa622007-08-15 14:28:22 +0000195
Georg Brandl116aa622007-08-15 14:28:22 +0000196 These represent numbers in an unlimited range, subject to available (virtual)
197 memory only. For the purpose of shift and mask operations, a binary
198 representation is assumed, and negative numbers are represented in a variant of
199 2's complement which gives the illusion of an infinite string of sign bits
200 extending to the left.
201
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000202 Booleans (:class:`bool`)
Georg Brandl116aa622007-08-15 14:28:22 +0000203 .. index::
204 object: Boolean
205 single: False
206 single: True
207
208 These represent the truth values False and True. The two objects representing
Serhiy Storchakafbc1c262013-11-29 12:17:13 +0200209 the values ``False`` and ``True`` are the only Boolean objects. The Boolean type is a
Georg Brandl95817b32008-05-11 14:30:18 +0000210 subtype of the integer type, and Boolean values behave like the values 0 and 1,
Georg Brandl116aa622007-08-15 14:28:22 +0000211 respectively, in almost all contexts, the exception being that when converted to
212 a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
213
214 .. index:: pair: integer; representation
215
216 The rules for integer representation are intended to give the most meaningful
Georg Brandlbb74a782008-05-11 10:53:16 +0000217 interpretation of shift and mask operations involving negative integers.
Georg Brandl116aa622007-08-15 14:28:22 +0000218
Christian Heimes072c0f12008-01-03 23:01:04 +0000219 :class:`numbers.Real` (:class:`float`)
Georg Brandl116aa622007-08-15 14:28:22 +0000220 .. index::
221 object: floating point
222 pair: floating point; number
223 pair: C; language
224 pair: Java; language
225
226 These represent machine-level double precision floating point numbers. You are
227 at the mercy of the underlying machine architecture (and C or Java
228 implementation) for the accepted range and handling of overflow. Python does not
229 support single-precision floating point numbers; the savings in processor and
Terry Jan Reedyb6271f22014-09-30 19:07:49 -0400230 memory usage that are usually the reason for using these are dwarfed by the
Georg Brandl116aa622007-08-15 14:28:22 +0000231 overhead of using objects in Python, so there is no reason to complicate the
232 language with two kinds of floating point numbers.
233
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000234 :class:`numbers.Complex` (:class:`complex`)
Georg Brandl116aa622007-08-15 14:28:22 +0000235 .. index::
236 object: complex
237 pair: complex; number
238
239 These represent complex numbers as a pair of machine-level double precision
240 floating point numbers. The same caveats apply as for floating point numbers.
241 The real and imaginary parts of a complex number ``z`` can be retrieved through
242 the read-only attributes ``z.real`` and ``z.imag``.
243
Georg Brandl116aa622007-08-15 14:28:22 +0000244Sequences
245 .. index::
246 builtin: len
247 object: sequence
248 single: index operation
249 single: item selection
250 single: subscription
251
252 These represent finite ordered sets indexed by non-negative numbers. The
253 built-in function :func:`len` returns the number of items of a sequence. When
254 the length of a sequence is *n*, the index set contains the numbers 0, 1,
255 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``.
256
257 .. index:: single: slicing
258
259 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
260 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
261 sequence of the same type. This implies that the index set is renumbered so
262 that it starts at 0.
263
Georg Brandl116aa622007-08-15 14:28:22 +0000264 Some sequences also support "extended slicing" with a third "step" parameter:
265 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
266 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
267
268 Sequences are distinguished according to their mutability:
269
270 Immutable sequences
271 .. index::
272 object: immutable sequence
273 object: immutable
274
275 An object of an immutable sequence type cannot change once it is created. (If
276 the object contains references to other objects, these other objects may be
277 mutable and may be changed; however, the collection of objects directly
278 referenced by an immutable object cannot change.)
279
280 The following types are immutable sequences:
281
Chris Jerdonekbb4e9412012-11-28 01:38:40 -0800282 .. index::
283 single: string; immutable sequences
284
Georg Brandl116aa622007-08-15 14:28:22 +0000285 Strings
286 .. index::
287 builtin: chr
288 builtin: ord
Georg Brandl116aa622007-08-15 14:28:22 +0000289 single: character
290 single: integer
291 single: Unicode
292
Nick Coghlan14627862014-06-07 23:21:14 +1000293 A string is a sequence of values that represent Unicode code points.
294 All the code points in the range ``U+0000 - U+10FFFF`` can be
295 represented in a string. Python doesn't have a :c:type:`char` type;
296 instead, every code point in the string is represented as a string
297 object with length ``1``. The built-in function :func:`ord`
298 converts a code point from its string form to an integer in the
299 range ``0 - 10FFFF``; :func:`chr` converts an integer in the range
300 ``0 - 10FFFF`` to the corresponding length ``1`` string object.
Ezio Melottif4d76e62011-10-25 09:23:42 +0300301 :meth:`str.encode` can be used to convert a :class:`str` to
Nick Coghlan14627862014-06-07 23:21:14 +1000302 :class:`bytes` using the given text encoding, and
303 :meth:`bytes.decode` can be used to achieve the opposite.
Georg Brandl116aa622007-08-15 14:28:22 +0000304
305 Tuples
306 .. index::
307 object: tuple
308 pair: singleton; tuple
309 pair: empty; tuple
310
Georg Brandldcc56f82007-08-31 16:41:12 +0000311 The items of a tuple are arbitrary Python objects. Tuples of two or
312 more items are formed by comma-separated lists of expressions. A tuple
313 of one item (a 'singleton') can be formed by affixing a comma to an
314 expression (an expression by itself does not create a tuple, since
315 parentheses must be usable for grouping of expressions). An empty
316 tuple can be formed by an empty pair of parentheses.
Georg Brandl116aa622007-08-15 14:28:22 +0000317
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000318 Bytes
319 .. index:: bytes, byte
320
321 A bytes object is an immutable array. The items are 8-bit bytes,
322 represented by integers in the range 0 <= x < 256. Bytes literals
Andrew Svetlovf5320352012-10-02 18:39:25 +0300323 (like ``b'abc'``) and the built-in function :func:`bytes` can be used to
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000324 construct bytes objects. Also, bytes objects can be decoded to strings
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300325 via the :meth:`~bytes.decode` method.
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000326
Georg Brandl116aa622007-08-15 14:28:22 +0000327 Mutable sequences
328 .. index::
329 object: mutable sequence
330 object: mutable
331 pair: assignment; statement
Georg Brandl116aa622007-08-15 14:28:22 +0000332 single: subscription
333 single: slicing
334
335 Mutable sequences can be changed after they are created. The subscription and
336 slicing notations can be used as the target of assignment and :keyword:`del`
337 (delete) statements.
338
Benjamin Petersonb58dda72009-01-18 22:27:04 +0000339 There are currently two intrinsic mutable sequence types:
Georg Brandl116aa622007-08-15 14:28:22 +0000340
341 Lists
342 .. index:: object: list
343
Georg Brandldcc56f82007-08-31 16:41:12 +0000344 The items of a list are arbitrary Python objects. Lists are formed by
345 placing a comma-separated list of expressions in square brackets. (Note
346 that there are no special cases needed to form lists of length 0 or 1.)
347
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000348 Byte Arrays
349 .. index:: bytearray
Georg Brandldcc56f82007-08-31 16:41:12 +0000350
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000351 A bytearray object is a mutable array. They are created by the built-in
352 :func:`bytearray` constructor. Aside from being mutable (and hence
353 unhashable), byte arrays otherwise provide the same interface and
354 functionality as immutable bytes objects.
Georg Brandl116aa622007-08-15 14:28:22 +0000355
356 .. index:: module: array
357
Georg Brandldcc56f82007-08-31 16:41:12 +0000358 The extension module :mod:`array` provides an additional example of a
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000359 mutable sequence type, as does the :mod:`collections` module.
Georg Brandl116aa622007-08-15 14:28:22 +0000360
Georg Brandl116aa622007-08-15 14:28:22 +0000361Set types
362 .. index::
363 builtin: len
364 object: set type
365
366 These represent unordered, finite sets of unique, immutable objects. As such,
367 they cannot be indexed by any subscript. However, they can be iterated over, and
368 the built-in function :func:`len` returns the number of items in a set. Common
369 uses for sets are fast membership testing, removing duplicates from a sequence,
370 and computing mathematical operations such as intersection, union, difference,
371 and symmetric difference.
372
373 For set elements, the same immutability rules apply as for dictionary keys. Note
374 that numeric types obey the normal rules for numeric comparison: if two numbers
375 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
376 set.
377
378 There are currently two intrinsic set types:
379
380 Sets
381 .. index:: object: set
382
383 These represent a mutable set. They are created by the built-in :func:`set`
384 constructor and can be modified afterwards by several methods, such as
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300385 :meth:`~set.add`.
Georg Brandl116aa622007-08-15 14:28:22 +0000386
387 Frozen sets
388 .. index:: object: frozenset
389
Guido van Rossum2cc30da2007-11-02 23:46:40 +0000390 These represent an immutable set. They are created by the built-in
391 :func:`frozenset` constructor. As a frozenset is immutable and
392 :term:`hashable`, it can be used again as an element of another set, or as
393 a dictionary key.
Georg Brandl116aa622007-08-15 14:28:22 +0000394
Georg Brandl116aa622007-08-15 14:28:22 +0000395Mappings
396 .. index::
397 builtin: len
398 single: subscription
399 object: mapping
400
401 These represent finite sets of objects indexed by arbitrary index sets. The
402 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
403 ``a``; this can be used in expressions and as the target of assignments or
404 :keyword:`del` statements. The built-in function :func:`len` returns the number
405 of items in a mapping.
406
407 There is currently a single intrinsic mapping type:
408
409 Dictionaries
410 .. index:: object: dictionary
411
412 These represent finite sets of objects indexed by nearly arbitrary values. The
413 only types of values not acceptable as keys are values containing lists or
414 dictionaries or other mutable types that are compared by value rather than by
415 object identity, the reason being that the efficient implementation of
416 dictionaries requires a key's hash value to remain constant. Numeric types used
417 for keys obey the normal rules for numeric comparison: if two numbers compare
418 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
419 the same dictionary entry.
420
421 Dictionaries are mutable; they can be created by the ``{...}`` notation (see
422 section :ref:`dict`).
423
424 .. index::
Georg Brandl0a7ac7d2008-05-26 10:29:35 +0000425 module: dbm.ndbm
426 module: dbm.gnu
Georg Brandl116aa622007-08-15 14:28:22 +0000427
Benjamin Peterson9a46cab2008-09-08 02:49:30 +0000428 The extension modules :mod:`dbm.ndbm` and :mod:`dbm.gnu` provide
429 additional examples of mapping types, as does the :mod:`collections`
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000430 module.
Georg Brandl116aa622007-08-15 14:28:22 +0000431
Georg Brandl116aa622007-08-15 14:28:22 +0000432Callable types
433 .. index::
434 object: callable
435 pair: function; call
436 single: invocation
437 pair: function; argument
438
439 These are the types to which the function call operation (see section
440 :ref:`calls`) can be applied:
441
442 User-defined functions
443 .. index::
444 pair: user-defined; function
445 object: function
446 object: user-defined function
447
448 A user-defined function object is created by a function definition (see
449 section :ref:`function`). It should be called with an argument list
450 containing the same number of items as the function's formal parameter
451 list.
452
453 Special attributes:
454
Georg Brandl44ea77b2013-03-28 13:28:44 +0100455 .. tabularcolumns:: |l|L|l|
456
Georg Brandl116aa622007-08-15 14:28:22 +0000457 +-------------------------+-------------------------------+-----------+
458 | Attribute | Meaning | |
459 +=========================+===============================+===========+
460 | :attr:`__doc__` | The function's documentation | Writable |
461 | | string, or ``None`` if | |
Ethan Furmanf87f5152014-10-17 22:25:22 -0700462 | | unavailable; not inherited by | |
463 | | subclasses | |
Georg Brandl116aa622007-08-15 14:28:22 +0000464 +-------------------------+-------------------------------+-----------+
465 | :attr:`__name__` | The function's name | Writable |
466 +-------------------------+-------------------------------+-----------+
Antoine Pitrou86a36b52011-11-25 18:56:07 +0100467 | :attr:`__qualname__` | The function's | Writable |
468 | | :term:`qualified name` | |
469 | | | |
470 | | .. versionadded:: 3.3 | |
471 +-------------------------+-------------------------------+-----------+
Georg Brandl116aa622007-08-15 14:28:22 +0000472 | :attr:`__module__` | The name of the module the | Writable |
473 | | function was defined in, or | |
474 | | ``None`` if unavailable. | |
475 +-------------------------+-------------------------------+-----------+
476 | :attr:`__defaults__` | A tuple containing default | Writable |
477 | | argument values for those | |
478 | | arguments that have defaults, | |
479 | | or ``None`` if no arguments | |
480 | | have a default value | |
481 +-------------------------+-------------------------------+-----------+
482 | :attr:`__code__` | The code object representing | Writable |
483 | | the compiled function body. | |
484 +-------------------------+-------------------------------+-----------+
485 | :attr:`__globals__` | A reference to the dictionary | Read-only |
486 | | that holds the function's | |
487 | | global variables --- the | |
488 | | global namespace of the | |
489 | | module in which the function | |
490 | | was defined. | |
491 +-------------------------+-------------------------------+-----------+
492 | :attr:`__dict__` | The namespace supporting | Writable |
493 | | arbitrary function | |
494 | | attributes. | |
495 +-------------------------+-------------------------------+-----------+
496 | :attr:`__closure__` | ``None`` or a tuple of cells | Read-only |
497 | | that contain bindings for the | |
498 | | function's free variables. | |
499 +-------------------------+-------------------------------+-----------+
500 | :attr:`__annotations__` | A dict containing annotations | Writable |
501 | | of parameters. The keys of | |
502 | | the dict are the parameter | |
Benjamin Peterson002033e2014-01-02 16:47:50 -0600503 | | names, and ``'return'`` for | |
Georg Brandl116aa622007-08-15 14:28:22 +0000504 | | the return annotation, if | |
505 | | provided. | |
506 +-------------------------+-------------------------------+-----------+
507 | :attr:`__kwdefaults__` | A dict containing defaults | Writable |
508 | | for keyword-only parameters. | |
509 +-------------------------+-------------------------------+-----------+
510
511 Most of the attributes labelled "Writable" check the type of the assigned value.
512
Georg Brandl116aa622007-08-15 14:28:22 +0000513 Function objects also support getting and setting arbitrary attributes, which
514 can be used, for example, to attach metadata to functions. Regular attribute
515 dot-notation is used to get and set such attributes. *Note that the current
516 implementation only supports function attributes on user-defined functions.
517 Function attributes on built-in functions may be supported in the future.*
518
519 Additional information about a function's definition can be retrieved from its
520 code object; see the description of internal types below.
521
522 .. index::
523 single: __doc__ (function attribute)
524 single: __name__ (function attribute)
525 single: __module__ (function attribute)
526 single: __dict__ (function attribute)
527 single: __defaults__ (function attribute)
528 single: __closure__ (function attribute)
529 single: __code__ (function attribute)
530 single: __globals__ (function attribute)
531 single: __annotations__ (function attribute)
532 single: __kwdefaults__ (function attribute)
533 pair: global; namespace
534
Georg Brandl2e0b7552007-11-27 12:43:08 +0000535 Instance methods
Georg Brandl116aa622007-08-15 14:28:22 +0000536 .. index::
537 object: method
538 object: user-defined method
539 pair: user-defined; method
540
Georg Brandl2e0b7552007-11-27 12:43:08 +0000541 An instance method object combines a class, a class instance and any
542 callable object (normally a user-defined function).
543
544 .. index::
545 single: __func__ (method attribute)
546 single: __self__ (method attribute)
547 single: __doc__ (method attribute)
548 single: __name__ (method attribute)
549 single: __module__ (method attribute)
Georg Brandl116aa622007-08-15 14:28:22 +0000550
Christian Heimesff737952007-11-27 10:40:20 +0000551 Special read-only attributes: :attr:`__self__` is the class instance object,
552 :attr:`__func__` is the function object; :attr:`__doc__` is the method's
553 documentation (same as ``__func__.__doc__``); :attr:`__name__` is the
554 method name (same as ``__func__.__name__``); :attr:`__module__` is the
555 name of the module the method was defined in, or ``None`` if unavailable.
Georg Brandl116aa622007-08-15 14:28:22 +0000556
Georg Brandl116aa622007-08-15 14:28:22 +0000557 Methods also support accessing (but not setting) the arbitrary function
558 attributes on the underlying function object.
559
Georg Brandl2e0b7552007-11-27 12:43:08 +0000560 User-defined method objects may be created when getting an attribute of a
561 class (perhaps via an instance of that class), if that attribute is a
562 user-defined function object or a class method object.
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000563
Georg Brandl2e0b7552007-11-27 12:43:08 +0000564 When an instance method object is created by retrieving a user-defined
565 function object from a class via one of its instances, its
566 :attr:`__self__` attribute is the instance, and the method object is said
567 to be bound. The new method's :attr:`__func__` attribute is the original
568 function object.
Georg Brandl116aa622007-08-15 14:28:22 +0000569
Georg Brandl2e0b7552007-11-27 12:43:08 +0000570 When a user-defined method object is created by retrieving another method
571 object from a class or instance, the behaviour is the same as for a
572 function object, except that the :attr:`__func__` attribute of the new
573 instance is not the original method object but its :attr:`__func__`
574 attribute.
Georg Brandl116aa622007-08-15 14:28:22 +0000575
Georg Brandl2e0b7552007-11-27 12:43:08 +0000576 When an instance method object is created by retrieving a class method
577 object from a class or instance, its :attr:`__self__` attribute is the
578 class itself, and its :attr:`__func__` attribute is the function object
579 underlying the class method.
Georg Brandl116aa622007-08-15 14:28:22 +0000580
Georg Brandl2e0b7552007-11-27 12:43:08 +0000581 When an instance method object is called, the underlying function
582 (:attr:`__func__`) is called, inserting the class instance
583 (:attr:`__self__`) in front of the argument list. For instance, when
584 :class:`C` is a class which contains a definition for a function
585 :meth:`f`, and ``x`` is an instance of :class:`C`, calling ``x.f(1)`` is
586 equivalent to calling ``C.f(x, 1)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000587
Georg Brandl2e0b7552007-11-27 12:43:08 +0000588 When an instance method object is derived from a class method object, the
589 "class instance" stored in :attr:`__self__` will actually be the class
590 itself, so that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to
591 calling ``f(C,1)`` where ``f`` is the underlying function.
Georg Brandl116aa622007-08-15 14:28:22 +0000592
Georg Brandl2e0b7552007-11-27 12:43:08 +0000593 Note that the transformation from function object to instance method
594 object happens each time the attribute is retrieved from the instance. In
595 some cases, a fruitful optimization is to assign the attribute to a local
596 variable and call that local variable. Also notice that this
597 transformation only happens for user-defined functions; other callable
598 objects (and all non-callable objects) are retrieved without
599 transformation. It is also important to note that user-defined functions
600 which are attributes of a class instance are not converted to bound
601 methods; this *only* happens when the function is an attribute of the
602 class.
Georg Brandl116aa622007-08-15 14:28:22 +0000603
604 Generator functions
605 .. index::
606 single: generator; function
607 single: generator; iterator
608
609 A function or method which uses the :keyword:`yield` statement (see section
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000610 :ref:`yield`) is called a :dfn:`generator function`. Such a function, when
611 called, always returns an iterator object which can be used to execute the
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300612 body of the function: calling the iterator's :meth:`iterator.__next__`
Ezio Melotti7fa82222012-10-12 13:42:08 +0300613 method will cause the function to execute until it provides a value
614 using the :keyword:`yield` statement. When the function executes a
Georg Brandl116aa622007-08-15 14:28:22 +0000615 :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
616 exception is raised and the iterator will have reached the end of the set of
617 values to be returned.
618
619 Built-in functions
620 .. index::
621 object: built-in function
622 object: function
623 pair: C; language
624
625 A built-in function object is a wrapper around a C function. Examples of
626 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
627 standard built-in module). The number and type of the arguments are
628 determined by the C function. Special read-only attributes:
629 :attr:`__doc__` is the function's documentation string, or ``None`` if
630 unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
631 set to ``None`` (but see the next item); :attr:`__module__` is the name of
632 the module the function was defined in or ``None`` if unavailable.
633
634 Built-in methods
635 .. index::
636 object: built-in method
637 object: method
638 pair: built-in; method
639
640 This is really a different disguise of a built-in function, this time containing
641 an object passed to the C function as an implicit extra argument. An example of
642 a built-in method is ``alist.append()``, assuming *alist* is a list object. In
643 this case, the special read-only attribute :attr:`__self__` is set to the object
Éric Araujoc9562f32010-12-26 02:18:49 +0000644 denoted by *alist*.
Georg Brandl116aa622007-08-15 14:28:22 +0000645
Georg Brandl85eb8c12007-08-31 16:33:38 +0000646 Classes
647 Classes are callable. These objects normally act as factories for new
648 instances of themselves, but variations are possible for class types that
649 override :meth:`__new__`. The arguments of the call are passed to
650 :meth:`__new__` and, in the typical case, to :meth:`__init__` to
651 initialize the new instance.
Georg Brandl116aa622007-08-15 14:28:22 +0000652
Georg Brandl85eb8c12007-08-31 16:33:38 +0000653 Class Instances
654 Instances of arbitrary classes can be made callable by defining a
655 :meth:`__call__` method in their class.
Georg Brandl116aa622007-08-15 14:28:22 +0000656
Georg Brandl116aa622007-08-15 14:28:22 +0000657
658Modules
659 .. index::
660 statement: import
661 object: module
662
Barry Warsawd7d21942012-07-29 16:36:17 -0400663 Modules are a basic organizational unit of Python code, and are created by
Barry Warsawdadebab2012-07-31 16:03:09 -0400664 the :ref:`import system <importsystem>` as invoked either by the
665 :keyword:`import` statement (see :keyword:`import`), or by calling
666 functions such as :func:`importlib.import_module` and built-in
667 :func:`__import__`. A module object has a namespace implemented by a
668 dictionary object (this is the dictionary referenced by the ``__globals__``
669 attribute of functions defined in the module). Attribute references are
670 translated to lookups in this dictionary, e.g., ``m.x`` is equivalent to
671 ``m.__dict__["x"]``. A module object does not contain the code object used
672 to initialize the module (since it isn't needed once the initialization is
673 done).
Georg Brandl116aa622007-08-15 14:28:22 +0000674
Barry Warsawd7d21942012-07-29 16:36:17 -0400675 Attribute assignment updates the module's namespace dictionary, e.g.,
676 ``m.x = 1`` is equivalent to ``m.__dict__["x"] = 1``.
Georg Brandl116aa622007-08-15 14:28:22 +0000677
678 .. index:: single: __dict__ (module attribute)
679
680 Special read-only attribute: :attr:`__dict__` is the module's namespace as a
681 dictionary object.
682
Benjamin Peterson5c4bfc42010-10-12 22:57:59 +0000683 .. impl-detail::
684
685 Because of the way CPython clears module dictionaries, the module
686 dictionary will be cleared when the module falls out of scope even if the
687 dictionary still has live references. To avoid this, copy the dictionary
688 or keep the module around while using its dictionary directly.
689
Georg Brandl116aa622007-08-15 14:28:22 +0000690 .. index::
691 single: __name__ (module attribute)
692 single: __doc__ (module attribute)
693 single: __file__ (module attribute)
694 pair: module; namespace
695
696 Predefined (writable) attributes: :attr:`__name__` is the module's name;
697 :attr:`__doc__` is the module's documentation string, or ``None`` if
Barry Warsawd7d21942012-07-29 16:36:17 -0400698 unavailable; :attr:`__file__` is the pathname of the file from which the
699 module was loaded, if it was loaded from a file. The :attr:`__file__`
700 attribute may be missing for certain types of modules, such as C modules
701 that are statically linked into the interpreter; for extension modules
702 loaded dynamically from a shared library, it is the pathname of the shared
703 library file.
Georg Brandl116aa622007-08-15 14:28:22 +0000704
Georg Brandl85eb8c12007-08-31 16:33:38 +0000705Custom classes
Georg Brandl5dbb84a2009-09-02 20:31:26 +0000706 Custom class types are typically created by class definitions (see section
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000707 :ref:`class`). A class has a namespace implemented by a dictionary object.
708 Class attribute references are translated to lookups in this dictionary, e.g.,
709 ``C.x`` is translated to ``C.__dict__["x"]`` (although there are a number of
710 hooks which allow for other means of locating attributes). When the attribute
711 name is not found there, the attribute search continues in the base classes.
712 This search of the base classes uses the C3 method resolution order which
713 behaves correctly even in the presence of 'diamond' inheritance structures
714 where there are multiple inheritance paths leading back to a common ancestor.
715 Additional details on the C3 MRO used by Python can be found in the
716 documentation accompanying the 2.3 release at
Georg Brandle73778c2014-10-29 08:36:35 +0100717 https://www.python.org/download/releases/2.3/mro/.
Georg Brandl116aa622007-08-15 14:28:22 +0000718
Nick Coghlan3a5d7e32008-08-31 12:40:14 +0000719 .. XXX: Could we add that MRO doc as an appendix to the language ref?
Georg Brandl85eb8c12007-08-31 16:33:38 +0000720
Georg Brandl116aa622007-08-15 14:28:22 +0000721 .. index::
722 object: class
723 object: class instance
724 object: instance
725 pair: class object; call
726 single: container
727 object: dictionary
728 pair: class; attribute
729
730 When a class attribute reference (for class :class:`C`, say) would yield a
Georg Brandl2e0b7552007-11-27 12:43:08 +0000731 class method object, it is transformed into an instance method object whose
732 :attr:`__self__` attributes is :class:`C`. When it would yield a static
733 method object, it is transformed into the object wrapped by the static method
734 object. See section :ref:`descriptors` for another way in which attributes
735 retrieved from a class may differ from those actually contained in its
736 :attr:`__dict__`.
Georg Brandl116aa622007-08-15 14:28:22 +0000737
738 .. index:: triple: class; attribute; assignment
739
740 Class attribute assignments update the class's dictionary, never the dictionary
741 of a base class.
742
743 .. index:: pair: class object; call
744
745 A class object can be called (see above) to yield a class instance (see below).
746
747 .. index::
748 single: __name__ (class attribute)
749 single: __module__ (class attribute)
750 single: __dict__ (class attribute)
751 single: __bases__ (class attribute)
752 single: __doc__ (class attribute)
753
754 Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
755 the module name in which the class was defined; :attr:`__dict__` is the
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300756 dictionary containing the class's namespace; :attr:`~class.__bases__` is a
757 tuple (possibly empty or a singleton) containing the base classes, in the
758 order of their occurrence in the base class list; :attr:`__doc__` is the
759 class's documentation string, or None if undefined.
Georg Brandl116aa622007-08-15 14:28:22 +0000760
761Class instances
762 .. index::
763 object: class instance
764 object: instance
765 pair: class; instance
766 pair: class instance; attribute
767
Georg Brandl2e0b7552007-11-27 12:43:08 +0000768 A class instance is created by calling a class object (see above). A class
769 instance has a namespace implemented as a dictionary which is the first place
770 in which attribute references are searched. When an attribute is not found
771 there, and the instance's class has an attribute by that name, the search
772 continues with the class attributes. If a class attribute is found that is a
773 user-defined function object, it is transformed into an instance method
774 object whose :attr:`__self__` attribute is the instance. Static method and
775 class method objects are also transformed; see above under "Classes". See
776 section :ref:`descriptors` for another way in which attributes of a class
777 retrieved via its instances may differ from the objects actually stored in
778 the class's :attr:`__dict__`. If no class attribute is found, and the
779 object's class has a :meth:`__getattr__` method, that is called to satisfy
780 the lookup.
Georg Brandl116aa622007-08-15 14:28:22 +0000781
782 .. index:: triple: class instance; attribute; assignment
783
784 Attribute assignments and deletions update the instance's dictionary, never a
785 class's dictionary. If the class has a :meth:`__setattr__` or
786 :meth:`__delattr__` method, this is called instead of updating the instance
787 dictionary directly.
788
789 .. index::
790 object: numeric
791 object: sequence
792 object: mapping
793
794 Class instances can pretend to be numbers, sequences, or mappings if they have
795 methods with certain special names. See section :ref:`specialnames`.
796
797 .. index::
798 single: __dict__ (instance attribute)
799 single: __class__ (instance attribute)
800
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300801 Special attributes: :attr:`~object.__dict__` is the attribute dictionary;
802 :attr:`~instance.__class__` is the instance's class.
Georg Brandl116aa622007-08-15 14:28:22 +0000803
Antoine Pitrou4adb2882010-01-04 18:50:53 +0000804I/O objects (also known as file objects)
Georg Brandl116aa622007-08-15 14:28:22 +0000805 .. index::
Georg Brandl116aa622007-08-15 14:28:22 +0000806 builtin: open
Antoine Pitrou4adb2882010-01-04 18:50:53 +0000807 module: io
Georg Brandl116aa622007-08-15 14:28:22 +0000808 single: popen() (in module os)
809 single: makefile() (socket method)
810 single: sys.stdin
811 single: sys.stdout
812 single: sys.stderr
813 single: stdio
814 single: stdin (in module sys)
815 single: stdout (in module sys)
816 single: stderr (in module sys)
817
Antoine Pitrou0b65b0f2010-09-15 09:58:26 +0000818 A :term:`file object` represents an open file. Various shortcuts are
819 available to create file objects: the :func:`open` built-in function, and
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +0300820 also :func:`os.popen`, :func:`os.fdopen`, and the
821 :meth:`~socket.socket.makefile` method of socket objects (and perhaps by
822 other functions or methods provided by extension modules).
Antoine Pitrou4adb2882010-01-04 18:50:53 +0000823
824 The objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are
825 initialized to file objects corresponding to the interpreter's standard
826 input, output and error streams; they are all open in text mode and
827 therefore follow the interface defined by the :class:`io.TextIOBase`
828 abstract class.
Georg Brandl116aa622007-08-15 14:28:22 +0000829
830Internal types
831 .. index::
832 single: internal type
833 single: types, internal
834
835 A few types used internally by the interpreter are exposed to the user. Their
836 definitions may change with future versions of the interpreter, but they are
837 mentioned here for completeness.
838
839 Code objects
840 .. index::
841 single: bytecode
842 object: code
843
Georg Brandl9afde1c2007-11-01 20:32:30 +0000844 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
Georg Brandl116aa622007-08-15 14:28:22 +0000845 The difference between a code object and a function object is that the function
846 object contains an explicit reference to the function's globals (the module in
847 which it was defined), while a code object contains no context; also the default
848 argument values are stored in the function object, not in the code object
849 (because they represent values calculated at run-time). Unlike function
850 objects, code objects are immutable and contain no references (directly or
851 indirectly) to mutable objects.
852
Senthil Kumaran7cafd262010-10-02 03:16:04 +0000853 .. index::
854 single: co_argcount (code object attribute)
855 single: co_code (code object attribute)
856 single: co_consts (code object attribute)
857 single: co_filename (code object attribute)
858 single: co_firstlineno (code object attribute)
859 single: co_flags (code object attribute)
860 single: co_lnotab (code object attribute)
861 single: co_name (code object attribute)
862 single: co_names (code object attribute)
863 single: co_nlocals (code object attribute)
864 single: co_stacksize (code object attribute)
865 single: co_varnames (code object attribute)
866 single: co_cellvars (code object attribute)
867 single: co_freevars (code object attribute)
868
Georg Brandl116aa622007-08-15 14:28:22 +0000869 Special read-only attributes: :attr:`co_name` gives the function name;
870 :attr:`co_argcount` is the number of positional arguments (including arguments
871 with default values); :attr:`co_nlocals` is the number of local variables used
872 by the function (including arguments); :attr:`co_varnames` is a tuple containing
873 the names of the local variables (starting with the argument names);
874 :attr:`co_cellvars` is a tuple containing the names of local variables that are
875 referenced by nested functions; :attr:`co_freevars` is a tuple containing the
876 names of free variables; :attr:`co_code` is a string representing the sequence
877 of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
878 used by the bytecode; :attr:`co_names` is a tuple containing the names used by
879 the bytecode; :attr:`co_filename` is the filename from which the code was
880 compiled; :attr:`co_firstlineno` is the first line number of the function;
Georg Brandl9afde1c2007-11-01 20:32:30 +0000881 :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to
Georg Brandl116aa622007-08-15 14:28:22 +0000882 line numbers (for details see the source code of the interpreter);
883 :attr:`co_stacksize` is the required stack size (including local variables);
884 :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
885
Georg Brandl116aa622007-08-15 14:28:22 +0000886 .. index:: object: generator
887
888 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
889 the function uses the ``*arguments`` syntax to accept an arbitrary number of
890 positional arguments; bit ``0x08`` is set if the function uses the
891 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
892 if the function is a generator.
893
894 Future feature declarations (``from __future__ import division``) also use bits
895 in :attr:`co_flags` to indicate whether a code object was compiled with a
896 particular feature enabled: bit ``0x2000`` is set if the function was compiled
897 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
898 versions of Python.
899
900 Other bits in :attr:`co_flags` are reserved for internal use.
901
902 .. index:: single: documentation string
903
904 If a code object represents a function, the first item in :attr:`co_consts` is
905 the documentation string of the function, or ``None`` if undefined.
906
Georg Brandla6053b42009-09-01 08:11:14 +0000907 .. _frame-objects:
908
Georg Brandl116aa622007-08-15 14:28:22 +0000909 Frame objects
910 .. index:: object: frame
911
912 Frame objects represent execution frames. They may occur in traceback objects
913 (see below).
914
915 .. index::
916 single: f_back (frame attribute)
917 single: f_code (frame attribute)
918 single: f_globals (frame attribute)
919 single: f_locals (frame attribute)
920 single: f_lasti (frame attribute)
921 single: f_builtins (frame attribute)
922
923 Special read-only attributes: :attr:`f_back` is to the previous stack frame
924 (towards the caller), or ``None`` if this is the bottom stack frame;
925 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
926 is the dictionary used to look up local variables; :attr:`f_globals` is used for
927 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
928 :attr:`f_lasti` gives the precise instruction (this is an index into the
929 bytecode string of the code object).
930
931 .. index::
932 single: f_trace (frame attribute)
Georg Brandl116aa622007-08-15 14:28:22 +0000933 single: f_lineno (frame attribute)
934
935 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
936 called at the start of each source code line (this is used by the debugger);
Benjamin Petersoneec3d712008-06-11 15:59:43 +0000937 :attr:`f_lineno` is the current line number of the frame --- writing to this
938 from within a trace function jumps to the given line (only for the bottom-most
939 frame). A debugger can implement a Jump command (aka Set Next Statement)
940 by writing to f_lineno.
Georg Brandl116aa622007-08-15 14:28:22 +0000941
Antoine Pitrou58720d62013-08-05 23:26:40 +0200942 Frame objects support one method:
943
944 .. method:: frame.clear()
945
946 This method clears all references to local variables held by the
947 frame. Also, if the frame belonged to a generator, the generator
948 is finalized. This helps break reference cycles involving frame
949 objects (for example when catching an exception and storing its
950 traceback for later use).
951
952 :exc:`RuntimeError` is raised if the frame is currently executing.
953
954 .. versionadded:: 3.4
955
Georg Brandl116aa622007-08-15 14:28:22 +0000956 Traceback objects
957 .. index::
958 object: traceback
959 pair: stack; trace
960 pair: exception; handler
961 pair: execution; stack
962 single: exc_info (in module sys)
Georg Brandl116aa622007-08-15 14:28:22 +0000963 single: last_traceback (in module sys)
964 single: sys.exc_info
965 single: sys.last_traceback
966
967 Traceback objects represent a stack trace of an exception. A traceback object
968 is created when an exception occurs. When the search for an exception handler
969 unwinds the execution stack, at each unwound level a traceback object is
970 inserted in front of the current traceback. When an exception handler is
971 entered, the stack trace is made available to the program. (See section
972 :ref:`try`.) It is accessible as the third item of the
973 tuple returned by ``sys.exc_info()``. When the program contains no suitable
974 handler, the stack trace is written (nicely formatted) to the standard error
975 stream; if the interpreter is interactive, it is also made available to the user
976 as ``sys.last_traceback``.
977
978 .. index::
979 single: tb_next (traceback attribute)
980 single: tb_frame (traceback attribute)
981 single: tb_lineno (traceback attribute)
982 single: tb_lasti (traceback attribute)
983 statement: try
984
985 Special read-only attributes: :attr:`tb_next` is the next level in the stack
986 trace (towards the frame where the exception occurred), or ``None`` if there is
987 no next level; :attr:`tb_frame` points to the execution frame of the current
988 level; :attr:`tb_lineno` gives the line number where the exception occurred;
989 :attr:`tb_lasti` indicates the precise instruction. The line number and last
990 instruction in the traceback may differ from the line number of its frame object
991 if the exception occurred in a :keyword:`try` statement with no matching except
992 clause or with a finally clause.
993
994 Slice objects
995 .. index:: builtin: slice
996
Georg Brandlcb8ecb12007-09-04 06:35:14 +0000997 Slice objects are used to represent slices for :meth:`__getitem__`
998 methods. They are also created by the built-in :func:`slice` function.
Georg Brandl116aa622007-08-15 14:28:22 +0000999
1000 .. index::
1001 single: start (slice object attribute)
1002 single: stop (slice object attribute)
1003 single: step (slice object attribute)
1004
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001005 Special read-only attributes: :attr:`~slice.start` is the lower bound;
1006 :attr:`~slice.stop` is the upper bound; :attr:`~slice.step` is the step
1007 value; each is ``None`` if omitted. These attributes can have any type.
Georg Brandl116aa622007-08-15 14:28:22 +00001008
1009 Slice objects support one method:
1010
Georg Brandl116aa622007-08-15 14:28:22 +00001011 .. method:: slice.indices(self, length)
1012
Georg Brandlcb8ecb12007-09-04 06:35:14 +00001013 This method takes a single integer argument *length* and computes
1014 information about the slice that the slice object would describe if
1015 applied to a sequence of *length* items. It returns a tuple of three
1016 integers; respectively these are the *start* and *stop* indices and the
1017 *step* or stride length of the slice. Missing or out-of-bounds indices
1018 are handled in a manner consistent with regular slices.
Georg Brandl116aa622007-08-15 14:28:22 +00001019
Georg Brandl116aa622007-08-15 14:28:22 +00001020 Static method objects
1021 Static method objects provide a way of defeating the transformation of function
1022 objects to method objects described above. A static method object is a wrapper
1023 around any other object, usually a user-defined method object. When a static
1024 method object is retrieved from a class or a class instance, the object actually
1025 returned is the wrapped object, which is not subject to any further
1026 transformation. Static method objects are not themselves callable, although the
1027 objects they wrap usually are. Static method objects are created by the built-in
1028 :func:`staticmethod` constructor.
1029
1030 Class method objects
1031 A class method object, like a static method object, is a wrapper around another
1032 object that alters the way in which that object is retrieved from classes and
1033 class instances. The behaviour of class method objects upon such retrieval is
1034 described above, under "User-defined methods". Class method objects are created
1035 by the built-in :func:`classmethod` constructor.
1036
Georg Brandl116aa622007-08-15 14:28:22 +00001037
Georg Brandl116aa622007-08-15 14:28:22 +00001038.. _specialnames:
1039
1040Special method names
1041====================
1042
1043.. index::
1044 pair: operator; overloading
1045 single: __getitem__() (mapping object method)
1046
1047A class can implement certain operations that are invoked by special syntax
1048(such as arithmetic operations or subscripting and slicing) by defining methods
1049with special names. This is Python's approach to :dfn:`operator overloading`,
1050allowing classes to define their own behavior with respect to language
1051operators. For instance, if a class defines a method named :meth:`__getitem__`,
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001052and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
1053to ``type(x).__getitem__(x, i)``. Except where mentioned, attempts to execute an
1054operation raise an exception when no appropriate method is defined (typically
1055:exc:`AttributeError` or :exc:`TypeError`).
Georg Brandl65ea9bd2007-09-05 13:36:27 +00001056
Georg Brandl116aa622007-08-15 14:28:22 +00001057When implementing a class that emulates any built-in type, it is important that
1058the emulation only be implemented to the degree that it makes sense for the
1059object being modelled. For example, some sequences may work well with retrieval
1060of individual elements, but extracting a slice may not make sense. (One example
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001061of this is the :class:`~xml.dom.NodeList` interface in the W3C's Document
1062Object Model.)
Georg Brandl116aa622007-08-15 14:28:22 +00001063
1064
1065.. _customization:
1066
1067Basic customization
1068-------------------
1069
Georg Brandl116aa622007-08-15 14:28:22 +00001070.. method:: object.__new__(cls[, ...])
1071
Georg Brandlaf265f42008-12-07 15:06:20 +00001072 .. index:: pair: subclassing; immutable types
1073
Georg Brandl116aa622007-08-15 14:28:22 +00001074 Called to create a new instance of class *cls*. :meth:`__new__` is a static
1075 method (special-cased so you need not declare it as such) that takes the class
1076 of which an instance was requested as its first argument. The remaining
1077 arguments are those passed to the object constructor expression (the call to the
1078 class). The return value of :meth:`__new__` should be the new object instance
1079 (usually an instance of *cls*).
1080
1081 Typical implementations create a new instance of the class by invoking the
1082 superclass's :meth:`__new__` method using ``super(currentclass,
1083 cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
1084 newly-created instance as necessary before returning it.
1085
1086 If :meth:`__new__` returns an instance of *cls*, then the new instance's
1087 :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
1088 *self* is the new instance and the remaining arguments are the same as were
1089 passed to :meth:`__new__`.
1090
1091 If :meth:`__new__` does not return an instance of *cls*, then the new instance's
1092 :meth:`__init__` method will not be invoked.
1093
1094 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like
Christian Heimes790c8232008-01-07 21:14:23 +00001095 int, str, or tuple) to customize instance creation. It is also commonly
1096 overridden in custom metaclasses in order to customize class creation.
Georg Brandl116aa622007-08-15 14:28:22 +00001097
1098
1099.. method:: object.__init__(self[, ...])
1100
1101 .. index:: pair: class; constructor
1102
Ethan Furman119479f2015-01-14 21:56:10 -08001103 Called after the instance has been created (by :meth:`__new__`), but before
1104 it is returned to the caller. The arguments are those passed to the
1105 class constructor expression. If a base class has an :meth:`__init__`
1106 method, the derived class's :meth:`__init__` method, if any, must explicitly
1107 call it to ensure proper initialization of the base class part of the
1108 instance; for example: ``BaseClass.__init__(self, [args...])``.
1109
1110 Because :meth:`__new__` and :meth:`__init__` work together in constructing
1111 objects (:meth:`__new__` to create it, and :meth:`__init__` to customise it),
1112 no non-``None`` value may be returned by :meth:`__init__`; doing so will
1113 cause a :exc:`TypeError` to be raised at runtime.
Georg Brandl116aa622007-08-15 14:28:22 +00001114
1115
1116.. method:: object.__del__(self)
1117
1118 .. index::
1119 single: destructor
1120 statement: del
1121
1122 Called when the instance is about to be destroyed. This is also called a
1123 destructor. If a base class has a :meth:`__del__` method, the derived class's
1124 :meth:`__del__` method, if any, must explicitly call it to ensure proper
1125 deletion of the base class part of the instance. Note that it is possible
1126 (though not recommended!) for the :meth:`__del__` method to postpone destruction
1127 of the instance by creating a new reference to it. It may then be called at a
1128 later time when this new reference is deleted. It is not guaranteed that
1129 :meth:`__del__` methods are called for objects that still exist when the
1130 interpreter exits.
1131
1132 .. note::
1133
1134 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
1135 the reference count for ``x`` by one, and the latter is only called when
1136 ``x``'s reference count reaches zero. Some common situations that may
1137 prevent the reference count of an object from going to zero include:
1138 circular references between objects (e.g., a doubly-linked list or a tree
1139 data structure with parent and child pointers); a reference to the object
1140 on the stack frame of a function that caught an exception (the traceback
1141 stored in ``sys.exc_info()[2]`` keeps the stack frame alive); or a
1142 reference to the object on the stack frame that raised an unhandled
1143 exception in interactive mode (the traceback stored in
1144 ``sys.last_traceback`` keeps the stack frame alive). The first situation
Georg Brandla4c8c472014-10-31 10:38:49 +01001145 can only be remedied by explicitly breaking the cycles; the second can be
1146 resolved by freeing the reference to the traceback object when it is no
1147 longer useful, and the third can be resolved by storing ``None`` in
1148 ``sys.last_traceback``.
Antoine Pitrou796564c2013-07-30 19:59:21 +02001149 Circular references which are garbage are detected and cleaned up when
1150 the cyclic garbage collector is enabled (it's on by default). Refer to the
1151 documentation for the :mod:`gc` module for more information about this
1152 topic.
Georg Brandl116aa622007-08-15 14:28:22 +00001153
1154 .. warning::
1155
1156 Due to the precarious circumstances under which :meth:`__del__` methods are
1157 invoked, exceptions that occur during their execution are ignored, and a warning
1158 is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in
1159 response to a module being deleted (e.g., when execution of the program is
1160 done), other globals referenced by the :meth:`__del__` method may already have
Brett Cannone1327f72009-01-29 04:10:21 +00001161 been deleted or in the process of being torn down (e.g. the import
1162 machinery shutting down). For this reason, :meth:`__del__` methods
1163 should do the absolute
Georg Brandl116aa622007-08-15 14:28:22 +00001164 minimum needed to maintain external invariants. Starting with version 1.5,
1165 Python guarantees that globals whose name begins with a single underscore are
1166 deleted from their module before other globals are deleted; if no other
1167 references to such globals exist, this may help in assuring that imported
1168 modules are still available at the time when the :meth:`__del__` method is
1169 called.
1170
Chris Jerdonek5fae0e52012-11-20 17:45:51 -08001171 .. index::
1172 single: repr() (built-in function); __repr__() (object method)
1173
Georg Brandl116aa622007-08-15 14:28:22 +00001174
1175.. method:: object.__repr__(self)
1176
Benjamin Peterson1c9313f2008-10-12 12:51:12 +00001177 Called by the :func:`repr` built-in function to compute the "official" string
1178 representation of an object. If at all possible, this should look like a
1179 valid Python expression that could be used to recreate an object with the
1180 same value (given an appropriate environment). If this is not possible, a
1181 string of the form ``<...some useful description...>`` should be returned.
1182 The return value must be a string object. If a class defines :meth:`__repr__`
1183 but not :meth:`__str__`, then :meth:`__repr__` is also used when an
1184 "informal" string representation of instances of that class is required.
Georg Brandl116aa622007-08-15 14:28:22 +00001185
Georg Brandl116aa622007-08-15 14:28:22 +00001186 This is typically used for debugging, so it is important that the representation
1187 is information-rich and unambiguous.
1188
Chris Jerdonek5fae0e52012-11-20 17:45:51 -08001189 .. index::
1190 single: string; __str__() (object method)
1191 single: format() (built-in function); __str__() (object method)
1192 single: print() (built-in function); __str__() (object method)
1193
Georg Brandl116aa622007-08-15 14:28:22 +00001194
1195.. method:: object.__str__(self)
1196
Chris Jerdonek5fae0e52012-11-20 17:45:51 -08001197 Called by :func:`str(object) <str>` and the built-in functions
1198 :func:`format` and :func:`print` to compute the "informal" or nicely
1199 printable string representation of an object. The return value must be a
1200 :ref:`string <textseq>` object.
Georg Brandl116aa622007-08-15 14:28:22 +00001201
Chris Jerdonek5fae0e52012-11-20 17:45:51 -08001202 This method differs from :meth:`object.__repr__` in that there is no
1203 expectation that :meth:`__str__` return a valid Python expression: a more
1204 convenient or concise representation can be used.
1205
1206 The default implementation defined by the built-in type :class:`object`
1207 calls :meth:`object.__repr__`.
Georg Brandl116aa622007-08-15 14:28:22 +00001208
Georg Brandldcc56f82007-08-31 16:41:12 +00001209 .. XXX what about subclasses of string?
1210
Georg Brandl116aa622007-08-15 14:28:22 +00001211
Benjamin Peterson1fafc1a2011-10-25 00:03:51 -04001212.. method:: object.__bytes__(self)
1213
1214 .. index:: builtin: bytes
1215
1216 Called by :func:`bytes` to compute a byte-string representation of an
1217 object. This should return a ``bytes`` object.
1218
Chris Jerdonekbb4e9412012-11-28 01:38:40 -08001219 .. index::
1220 single: string; __format__() (object method)
1221 pair: string; conversion
1222 builtin: print
1223
Benjamin Peterson1fafc1a2011-10-25 00:03:51 -04001224
Georg Brandl4b491312007-08-31 09:22:56 +00001225.. method:: object.__format__(self, format_spec)
1226
Georg Brandl4b491312007-08-31 09:22:56 +00001227 Called by the :func:`format` built-in function (and by extension, the
Chris Jerdonekaf947242012-10-11 18:47:54 -07001228 :meth:`str.format` method of class :class:`str`) to produce a "formatted"
Georg Brandl4b491312007-08-31 09:22:56 +00001229 string representation of an object. The ``format_spec`` argument is
1230 a string that contains a description of the formatting options desired.
1231 The interpretation of the ``format_spec`` argument is up to the type
1232 implementing :meth:`__format__`, however most classes will either
1233 delegate formatting to one of the built-in types, or use a similar
1234 formatting option syntax.
Georg Brandl48310cd2009-01-03 21:18:54 +00001235
Georg Brandl4b491312007-08-31 09:22:56 +00001236 See :ref:`formatspec` for a description of the standard formatting syntax.
1237
1238 The return value must be a string object.
1239
Larry Hastings3732ed22014-03-15 21:13:56 -07001240 .. versionchanged:: 3.4
1241 The __format__ method of ``object`` itself raises a :exc:`TypeError`
1242 if passed any non-empty string.
1243
Georg Brandl4b491312007-08-31 09:22:56 +00001244
Georg Brandl33413cb2009-03-31 19:06:37 +00001245.. _richcmpfuncs:
Georg Brandl116aa622007-08-15 14:28:22 +00001246.. method:: object.__lt__(self, other)
1247 object.__le__(self, other)
1248 object.__eq__(self, other)
1249 object.__ne__(self, other)
1250 object.__gt__(self, other)
1251 object.__ge__(self, other)
1252
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001253 .. index::
1254 single: comparisons
1255
Georg Brandl05f5ab72008-09-24 09:11:47 +00001256 These are the so-called "rich comparison" methods. The correspondence between
Georg Brandl116aa622007-08-15 14:28:22 +00001257 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
1258 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls
1259 ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
1260 ``x.__ge__(y)``.
1261
1262 A rich comparison method may return the singleton ``NotImplemented`` if it does
1263 not implement the operation for a given pair of arguments. By convention,
1264 ``False`` and ``True`` are returned for a successful comparison. However, these
1265 methods can return any value, so if the comparison operator is used in a Boolean
1266 context (e.g., in the condition of an ``if`` statement), Python will call
1267 :func:`bool` on the value to determine if the result is true or false.
1268
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001269 There are no implied relationships among the comparison operators. The truth
1270 of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when
1271 defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the
1272 operators will behave as expected. See the paragraph on :meth:`__hash__` for
1273 some important notes on creating :term:`hashable` objects which support
1274 custom comparison operations and are usable as dictionary keys.
Georg Brandl116aa622007-08-15 14:28:22 +00001275
Guido van Rossum2cc30da2007-11-02 23:46:40 +00001276 There are no swapped-argument versions of these methods (to be used when the
1277 left argument does not support the operation but the right argument does);
1278 rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
Georg Brandl116aa622007-08-15 14:28:22 +00001279 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and
1280 :meth:`__eq__` and :meth:`__ne__` are their own reflection.
1281
1282 Arguments to rich comparison methods are never coerced.
1283
Raymond Hettinger6c4b4b22009-03-12 00:25:29 +00001284 To automatically generate ordering operations from a single root operation,
Raymond Hettingerc50846a2010-04-05 18:56:31 +00001285 see :func:`functools.total_ordering`.
Georg Brandl116aa622007-08-15 14:28:22 +00001286
Georg Brandl116aa622007-08-15 14:28:22 +00001287.. method:: object.__hash__(self)
1288
1289 .. index::
1290 object: dictionary
1291 builtin: hash
1292
Benjamin Peterson6cadba72008-11-19 22:38:29 +00001293 Called by built-in function :func:`hash` and for operations on members of
1294 hashed collections including :class:`set`, :class:`frozenset`, and
Barry Warsaw224a5992013-07-15 14:47:29 -04001295 :class:`dict`. :meth:`__hash__` should return an integer. The only
1296 required property is that objects which compare equal have the same hash
1297 value; it is advised to somehow mix together (e.g. using exclusive or) the
1298 hash values for the components of the object that also play a part in
1299 comparison of objects.
1300
1301 .. note::
1302
1303 :func:`hash` truncates the value returned from an object's custom
1304 :meth:`__hash__` method to the size of a :c:type:`Py_ssize_t`. This is
1305 typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds. If an
1306 object's :meth:`__hash__` must interoperate on builds of different bit
1307 sizes, be sure to check the width on all supported builds. An easy way
1308 to do this is with
1309 ``python -c "import sys; print(sys.hash_info.width)"``
Georg Brandl116aa622007-08-15 14:28:22 +00001310
Georg Brandl05f5ab72008-09-24 09:11:47 +00001311 If a class does not define an :meth:`__eq__` method it should not define a
1312 :meth:`__hash__` operation either; if it defines :meth:`__eq__` but not
Benjamin Peterson6cadba72008-11-19 22:38:29 +00001313 :meth:`__hash__`, its instances will not be usable as items in hashable
1314 collections. If a class defines mutable objects and implements an
1315 :meth:`__eq__` method, it should not implement :meth:`__hash__`, since the
1316 implementation of hashable collections requires that a key's hash value is
1317 immutable (if the object's hash value changes, it will be in the wrong hash
1318 bucket).
1319
Georg Brandl05f5ab72008-09-24 09:11:47 +00001320 User-defined classes have :meth:`__eq__` and :meth:`__hash__` methods
Nick Coghlan73c96db2008-08-31 13:21:24 +00001321 by default; with them, all objects compare unequal (except with themselves)
Nick Coghlan337b2bf2012-05-20 18:30:49 +10001322 and ``x.__hash__()`` returns an appropriate value such that ``x == y``
1323 implies both that ``x is y`` and ``hash(x) == hash(y)``.
1324
R David Murrayd8bbde32012-09-11 13:01:43 -04001325 A class that overrides :meth:`__eq__` and does not define :meth:`__hash__`
1326 will have its :meth:`__hash__` implicitly set to ``None``. When the
1327 :meth:`__hash__` method of a class is ``None``, instances of the class will
1328 raise an appropriate :exc:`TypeError` when a program attempts to retrieve
1329 their hash value, and will also be correctly identified as unhashable when
1330 checking ``isinstance(obj, collections.Hashable``).
Nick Coghlan73c96db2008-08-31 13:21:24 +00001331
Georg Brandlae2dbe22009-03-13 19:04:40 +00001332 If a class that overrides :meth:`__eq__` needs to retain the implementation
Georg Brandl05f5ab72008-09-24 09:11:47 +00001333 of :meth:`__hash__` from a parent class, the interpreter must be told this
R David Murrayd8bbde32012-09-11 13:01:43 -04001334 explicitly by setting ``__hash__ = <ParentClass>.__hash__``.
1335
1336 If a class that does not override :meth:`__eq__` wishes to suppress hash
1337 support, it should include ``__hash__ = None`` in the class definition.
1338 A class which defines its own :meth:`__hash__` that explicitly raises
1339 a :exc:`TypeError` would be incorrectly identified as hashable by
1340 an ``isinstance(obj, collections.Hashable)`` call.
Georg Brandl05f5ab72008-09-24 09:11:47 +00001341
Benjamin Petersonc9f54cf2012-02-21 16:08:05 -05001342
1343 .. note::
1344
Antoine Pitrouc86e8d92012-08-01 14:53:22 +02001345 By default, the :meth:`__hash__` values of str, bytes and datetime
Benjamin Petersonc9f54cf2012-02-21 16:08:05 -05001346 objects are "salted" with an unpredictable random value. Although they
1347 remain constant within an individual Python process, they are not
1348 predictable between repeated invocations of Python.
1349
1350 This is intended to provide protection against a denial-of-service caused
1351 by carefully-chosen inputs that exploit the worst case performance of a
1352 dict insertion, O(n^2) complexity. See
1353 http://www.ocert.org/advisories/ocert-2011-003.html for details.
1354
Antoine Pitrouc86e8d92012-08-01 14:53:22 +02001355 Changing hash values affects the iteration order of dicts, sets and
1356 other mappings. Python has never made guarantees about this ordering
1357 (and it typically varies between 32-bit and 64-bit builds).
Benjamin Petersonc9f54cf2012-02-21 16:08:05 -05001358
1359 See also :envvar:`PYTHONHASHSEED`.
1360
1361 .. versionchanged:: 3.3
1362 Hash randomization is enabled by default.
Georg Brandl2daf6ae2012-02-20 19:54:16 +01001363
Georg Brandl116aa622007-08-15 14:28:22 +00001364
1365.. method:: object.__bool__(self)
Georg Brandl1aeaadd2008-09-06 17:42:52 +00001366
Georg Brandl116aa622007-08-15 14:28:22 +00001367 .. index:: single: __len__() (mapping object method)
1368
Benjamin Petersonf07d0022009-03-21 17:31:58 +00001369 Called to implement truth value testing and the built-in operation
Amaury Forgeot d'Arc097cd072009-07-07 00:43:08 +00001370 ``bool()``; should return ``False`` or ``True``. When this method is not
1371 defined, :meth:`__len__` is called, if it is defined, and the object is
1372 considered true if its result is nonzero. If a class defines neither
1373 :meth:`__len__` nor :meth:`__bool__`, all its instances are considered
1374 true.
Georg Brandl116aa622007-08-15 14:28:22 +00001375
1376
Georg Brandl116aa622007-08-15 14:28:22 +00001377.. _attribute-access:
1378
1379Customizing attribute access
1380----------------------------
1381
1382The following methods can be defined to customize the meaning of attribute
1383access (use of, assignment to, or deletion of ``x.name``) for class instances.
1384
Georg Brandl85eb8c12007-08-31 16:33:38 +00001385.. XXX explain how descriptors interfere here!
1386
Georg Brandl116aa622007-08-15 14:28:22 +00001387
1388.. method:: object.__getattr__(self, name)
1389
1390 Called when an attribute lookup has not found the attribute in the usual places
1391 (i.e. it is not an instance attribute nor is it found in the class tree for
1392 ``self``). ``name`` is the attribute name. This method should return the
1393 (computed) attribute value or raise an :exc:`AttributeError` exception.
1394
Georg Brandl116aa622007-08-15 14:28:22 +00001395 Note that if the attribute is found through the normal mechanism,
1396 :meth:`__getattr__` is not called. (This is an intentional asymmetry between
1397 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001398 reasons and because otherwise :meth:`__getattr__` would have no way to access
Georg Brandl116aa622007-08-15 14:28:22 +00001399 other attributes of the instance. Note that at least for instance variables,
1400 you can fake total control by not inserting any values in the instance attribute
1401 dictionary (but instead inserting them in another object). See the
Georg Brandl85eb8c12007-08-31 16:33:38 +00001402 :meth:`__getattribute__` method below for a way to actually get total control
1403 over attribute access.
Georg Brandl116aa622007-08-15 14:28:22 +00001404
1405
1406.. method:: object.__getattribute__(self, name)
1407
1408 Called unconditionally to implement attribute accesses for instances of the
1409 class. If the class also defines :meth:`__getattr__`, the latter will not be
1410 called unless :meth:`__getattribute__` either calls it explicitly or raises an
1411 :exc:`AttributeError`. This method should return the (computed) attribute value
1412 or raise an :exc:`AttributeError` exception. In order to avoid infinite
1413 recursion in this method, its implementation should always call the base class
1414 method with the same name to access any attributes it needs, for example,
1415 ``object.__getattribute__(self, name)``.
1416
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001417 .. note::
1418
1419 This method may still be bypassed when looking up special methods as the
Georg Brandl22b34312009-07-26 14:54:51 +00001420 result of implicit invocation via language syntax or built-in functions.
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00001421 See :ref:`special-lookup`.
1422
Georg Brandl116aa622007-08-15 14:28:22 +00001423
Georg Brandl85eb8c12007-08-31 16:33:38 +00001424.. method:: object.__setattr__(self, name, value)
1425
1426 Called when an attribute assignment is attempted. This is called instead of
1427 the normal mechanism (i.e. store the value in the instance dictionary).
1428 *name* is the attribute name, *value* is the value to be assigned to it.
1429
1430 If :meth:`__setattr__` wants to assign to an instance attribute, it should
1431 call the base class method with the same name, for example,
1432 ``object.__setattr__(self, name, value)``.
1433
1434
1435.. method:: object.__delattr__(self, name)
1436
1437 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
1438 should only be implemented if ``del obj.name`` is meaningful for the object.
1439
1440
Benjamin Peterson1cef37c2008-07-02 14:44:54 +00001441.. method:: object.__dir__(self)
1442
Benjamin Peterson3bbb7222011-06-11 16:12:08 -05001443 Called when :func:`dir` is called on the object. A sequence must be
1444 returned. :func:`dir` converts the returned sequence to a list and sorts it.
Benjamin Peterson1cef37c2008-07-02 14:44:54 +00001445
1446
Georg Brandl116aa622007-08-15 14:28:22 +00001447.. _descriptors:
1448
1449Implementing Descriptors
1450^^^^^^^^^^^^^^^^^^^^^^^^
1451
1452The following methods only apply when an instance of the class containing the
Raymond Hettinger3b654be2011-03-22 16:27:02 -07001453method (a so-called *descriptor* class) appears in an *owner* class (the
1454descriptor must be in either the owner's class dictionary or in the class
1455dictionary for one of its parents). In the examples below, "the attribute"
1456refers to the attribute whose name is the key of the property in the owner
1457class' :attr:`__dict__`.
Georg Brandl116aa622007-08-15 14:28:22 +00001458
1459
1460.. method:: object.__get__(self, instance, owner)
1461
1462 Called to get the attribute of the owner class (class attribute access) or of an
1463 instance of that class (instance attribute access). *owner* is always the owner
1464 class, while *instance* is the instance that the attribute was accessed through,
1465 or ``None`` when the attribute is accessed through the *owner*. This method
1466 should return the (computed) attribute value or raise an :exc:`AttributeError`
1467 exception.
1468
1469
1470.. method:: object.__set__(self, instance, value)
1471
1472 Called to set the attribute on an instance *instance* of the owner class to a
1473 new value, *value*.
1474
1475
1476.. method:: object.__delete__(self, instance)
1477
1478 Called to delete the attribute on an instance *instance* of the owner class.
1479
1480
Yury Selivanovaf8a4df2014-04-08 14:00:35 -04001481The attribute :attr:`__objclass__` is interpreted by the :mod:`inspect` module
1482as specifying the class where this object was defined (setting this
1483appropriately can assist in runtime introspection of dynamic class attributes).
1484For callables, it may indicate that an instance of the given type (or a
1485subclass) is expected or required as the first positional argument (for example,
1486CPython sets this attribute for unbound methods that are implemented in C).
Yury Selivanovd3f918c2014-04-08 12:03:07 -04001487
1488
Georg Brandl116aa622007-08-15 14:28:22 +00001489.. _descriptor-invocation:
1490
1491Invoking Descriptors
1492^^^^^^^^^^^^^^^^^^^^
1493
1494In general, a descriptor is an object attribute with "binding behavior", one
1495whose attribute access has been overridden by methods in the descriptor
1496protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
1497those methods are defined for an object, it is said to be a descriptor.
1498
1499The default behavior for attribute access is to get, set, or delete the
1500attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
1501starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
1502continuing through the base classes of ``type(a)`` excluding metaclasses.
1503
1504However, if the looked-up value is an object defining one of the descriptor
1505methods, then Python may override the default behavior and invoke the descriptor
1506method instead. Where this occurs in the precedence chain depends on which
Georg Brandl23e8db52008-04-07 19:17:06 +00001507descriptor methods were defined and how they were called.
Georg Brandl116aa622007-08-15 14:28:22 +00001508
1509The starting point for descriptor invocation is a binding, ``a.x``. How the
1510arguments are assembled depends on ``a``:
1511
1512Direct Call
1513 The simplest and least common call is when user code directly invokes a
1514 descriptor method: ``x.__get__(a)``.
1515
1516Instance Binding
Georg Brandl85eb8c12007-08-31 16:33:38 +00001517 If binding to an object instance, ``a.x`` is transformed into the call:
Georg Brandl116aa622007-08-15 14:28:22 +00001518 ``type(a).__dict__['x'].__get__(a, type(a))``.
1519
1520Class Binding
Georg Brandl85eb8c12007-08-31 16:33:38 +00001521 If binding to a class, ``A.x`` is transformed into the call:
Georg Brandl116aa622007-08-15 14:28:22 +00001522 ``A.__dict__['x'].__get__(None, A)``.
1523
1524Super Binding
1525 If ``a`` is an instance of :class:`super`, then the binding ``super(B,
1526 obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
1527 immediately preceding ``B`` and then invokes the descriptor with the call:
Raymond Hettingerb199b222011-03-22 15:28:45 -07001528 ``A.__dict__['m'].__get__(obj, obj.__class__)``.
Georg Brandl116aa622007-08-15 14:28:22 +00001529
1530For instance bindings, the precedence of descriptor invocation depends on the
Benjamin Peterson5e55b3e2010-02-03 02:35:45 +00001531which descriptor methods are defined. A descriptor can define any combination
1532of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not
1533define :meth:`__get__`, then accessing the attribute will return the descriptor
1534object itself unless there is a value in the object's instance dictionary. If
1535the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data
1536descriptor; if it defines neither, it is a non-data descriptor. Normally, data
1537descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data
1538descriptors have just the :meth:`__get__` method. Data descriptors with
1539:meth:`__set__` and :meth:`__get__` defined always override a redefinition in an
Georg Brandl116aa622007-08-15 14:28:22 +00001540instance dictionary. In contrast, non-data descriptors can be overridden by
Benjamin Peterson5e55b3e2010-02-03 02:35:45 +00001541instances.
Georg Brandl116aa622007-08-15 14:28:22 +00001542
1543Python methods (including :func:`staticmethod` and :func:`classmethod`) are
1544implemented as non-data descriptors. Accordingly, instances can redefine and
1545override methods. This allows individual instances to acquire behaviors that
1546differ from other instances of the same class.
1547
1548The :func:`property` function is implemented as a data descriptor. Accordingly,
1549instances cannot override the behavior of a property.
1550
1551
1552.. _slots:
1553
1554__slots__
1555^^^^^^^^^
1556
Georg Brandl85eb8c12007-08-31 16:33:38 +00001557By default, instances of classes have a dictionary for attribute storage. This
1558wastes space for objects having very few instance variables. The space
1559consumption can become acute when creating large numbers of instances.
Georg Brandl116aa622007-08-15 14:28:22 +00001560
Georg Brandl85eb8c12007-08-31 16:33:38 +00001561The default can be overridden by defining *__slots__* in a class definition.
1562The *__slots__* declaration takes a sequence of instance variables and reserves
1563just enough space in each instance to hold a value for each variable. Space is
1564saved because *__dict__* is not created for each instance.
Georg Brandl116aa622007-08-15 14:28:22 +00001565
1566
Georg Brandl85eb8c12007-08-31 16:33:38 +00001567.. data:: object.__slots__
Georg Brandl116aa622007-08-15 14:28:22 +00001568
Georg Brandl85eb8c12007-08-31 16:33:38 +00001569 This class variable can be assigned a string, iterable, or sequence of
Georg Brandla4c8c472014-10-31 10:38:49 +01001570 strings with variable names used by instances. *__slots__* reserves space
1571 for the declared variables and prevents the automatic creation of *__dict__*
1572 and *__weakref__* for each instance.
Georg Brandl116aa622007-08-15 14:28:22 +00001573
Georg Brandl116aa622007-08-15 14:28:22 +00001574
1575Notes on using *__slots__*
Georg Brandl16174572007-09-01 12:38:06 +00001576""""""""""""""""""""""""""
Georg Brandl116aa622007-08-15 14:28:22 +00001577
Georg Brandl3dbca812008-07-23 16:10:53 +00001578* When inheriting from a class without *__slots__*, the *__dict__* attribute of
1579 that class will always be accessible, so a *__slots__* definition in the
1580 subclass is meaningless.
1581
Georg Brandl116aa622007-08-15 14:28:22 +00001582* Without a *__dict__* variable, instances cannot be assigned new variables not
1583 listed in the *__slots__* definition. Attempts to assign to an unlisted
1584 variable name raises :exc:`AttributeError`. If dynamic assignment of new
Georg Brandl85eb8c12007-08-31 16:33:38 +00001585 variables is desired, then add ``'__dict__'`` to the sequence of strings in
1586 the *__slots__* declaration.
Georg Brandl116aa622007-08-15 14:28:22 +00001587
Georg Brandl116aa622007-08-15 14:28:22 +00001588* Without a *__weakref__* variable for each instance, classes defining
1589 *__slots__* do not support weak references to its instances. If weak reference
1590 support is needed, then add ``'__weakref__'`` to the sequence of strings in the
1591 *__slots__* declaration.
1592
Georg Brandl116aa622007-08-15 14:28:22 +00001593* *__slots__* are implemented at the class level by creating descriptors
1594 (:ref:`descriptors`) for each variable name. As a result, class attributes
1595 cannot be used to set default values for instance variables defined by
1596 *__slots__*; otherwise, the class attribute would overwrite the descriptor
1597 assignment.
1598
Georg Brandl495f7b52009-10-27 15:28:25 +00001599* The action of a *__slots__* declaration is limited to the class where it is
1600 defined. As a result, subclasses will have a *__dict__* unless they also define
1601 *__slots__* (which must only contain names of any *additional* slots).
1602
Georg Brandl116aa622007-08-15 14:28:22 +00001603* If a class defines a slot also defined in a base class, the instance variable
1604 defined by the base class slot is inaccessible (except by retrieving its
1605 descriptor directly from the base class). This renders the meaning of the
1606 program undefined. In the future, a check may be added to prevent this.
1607
Benjamin Peterson1a6e0d02008-10-25 15:49:17 +00001608* Nonempty *__slots__* does not work for classes derived from "variable-length"
Zachary Ware340a6922013-12-31 12:09:26 -06001609 built-in types such as :class:`int`, :class:`bytes` and :class:`tuple`.
Georg Brandl116aa622007-08-15 14:28:22 +00001610
1611* Any non-string iterable may be assigned to *__slots__*. Mappings may also be
1612 used; however, in the future, special meaning may be assigned to the values
1613 corresponding to each key.
1614
1615* *__class__* assignment works only if both classes have the same *__slots__*.
1616
Georg Brandl116aa622007-08-15 14:28:22 +00001617
1618.. _metaclasses:
1619
1620Customizing class creation
1621--------------------------
1622
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001623By default, classes are constructed using :func:`type`. The class body is
1624executed in a new namespace and the class name is bound locally to the
1625result of ``type(name, bases, namespace)``.
Georg Brandl116aa622007-08-15 14:28:22 +00001626
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001627The class creation process can be customised by passing the ``metaclass``
1628keyword argument in the class definition line, or by inheriting from an
1629existing class that included such an argument. In the following example,
1630both ``MyClass`` and ``MySubclass`` are instances of ``Meta``::
Georg Brandl116aa622007-08-15 14:28:22 +00001631
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001632 class Meta(type):
1633 pass
Georg Brandl116aa622007-08-15 14:28:22 +00001634
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001635 class MyClass(metaclass=Meta):
1636 pass
Georg Brandl116aa622007-08-15 14:28:22 +00001637
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001638 class MySubclass(MyClass):
1639 pass
Christian Heimes790c8232008-01-07 21:14:23 +00001640
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001641Any other keyword arguments that are specified in the class definition are
1642passed through to all metaclass operations described below.
Christian Heimes790c8232008-01-07 21:14:23 +00001643
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001644When a class definition is executed, the following steps occur:
Christian Heimes790c8232008-01-07 21:14:23 +00001645
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001646* the appropriate metaclass is determined
1647* the class namespace is prepared
1648* the class body is executed
1649* the class object is created
Georg Brandl116aa622007-08-15 14:28:22 +00001650
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001651Determining the appropriate metaclass
1652^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Georg Brandl116aa622007-08-15 14:28:22 +00001653
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001654The appropriate metaclass for a class definition is determined as follows:
Georg Brandl116aa622007-08-15 14:28:22 +00001655
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001656* if no bases and no explicit metaclass are given, then :func:`type` is used
1657* if an explicit metaclass is given and it is *not* an instance of
1658 :func:`type`, then it is used directly as the metaclass
1659* if an instance of :func:`type` is given as the explicit metaclass, or
1660 bases are defined, then the most derived metaclass is used
Georg Brandl116aa622007-08-15 14:28:22 +00001661
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001662The most derived metaclass is selected from the explicitly specified
1663metaclass (if any) and the metaclasses (i.e. ``type(cls)``) of all specified
1664base classes. The most derived metaclass is one which is a subtype of *all*
1665of these candidate metaclasses. If none of the candidate metaclasses meets
1666that criterion, then the class definition will fail with ``TypeError``.
1667
1668
Larry Hastings3732ed22014-03-15 21:13:56 -07001669.. _prepare:
1670
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001671Preparing the class namespace
1672^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1673
1674Once the appropriate metaclass has been identified, then the class namespace
1675is prepared. If the metaclass has a ``__prepare__`` attribute, it is called
1676as ``namespace = metaclass.__prepare__(name, bases, **kwds)`` (where the
1677additional keyword arguments, if any, come from the class definition).
1678
1679If the metaclass has no ``__prepare__`` attribute, then the class namespace
1680is initialised as an empty :func:`dict` instance.
1681
1682.. seealso::
1683
1684 :pep:`3115` - Metaclasses in Python 3000
1685 Introduced the ``__prepare__`` namespace hook
1686
1687
1688Executing the class body
1689^^^^^^^^^^^^^^^^^^^^^^^^
1690
1691The class body is executed (approximately) as
1692``exec(body, globals(), namespace)``. The key difference from a normal
1693call to :func:`exec` is that lexical scoping allows the class body (including
1694any methods) to reference names from the current and outer scopes when the
1695class definition occurs inside a function.
1696
1697However, even when the class definition occurs inside the function, methods
1698defined inside the class still cannot see names defined at the class scope.
1699Class variables must be accessed through the first parameter of instance or
1700class methods, and cannot be accessed at all from static methods.
1701
1702
1703Creating the class object
1704^^^^^^^^^^^^^^^^^^^^^^^^^
1705
1706Once the class namespace has been populated by executing the class body,
1707the class object is created by calling
1708``metaclass(name, bases, namespace, **kwds)`` (the additional keywords
Nick Coghlan78770f02012-05-20 18:15:11 +10001709passed here are the same as those passed to ``__prepare__``).
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001710
1711This class object is the one that will be referenced by the zero-argument
1712form of :func:`super`. ``__class__`` is an implicit closure reference
1713created by the compiler if any methods in a class body refer to either
1714``__class__`` or ``super``. This allows the zero argument form of
1715:func:`super` to correctly identify the class being defined based on
1716lexical scoping, while the class or instance that was used to make the
1717current call is identified based on the first argument passed to the method.
1718
Nick Coghlanb2674752012-05-20 19:36:40 +10001719After the class object is created, it is passed to the class decorators
1720included in the class definition (if any) and the resulting object is bound
1721in the local namespace as the defined class.
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001722
1723.. seealso::
1724
1725 :pep:`3135` - New super
1726 Describes the implicit ``__class__`` closure reference
1727
1728
1729Metaclass example
1730^^^^^^^^^^^^^^^^^
Georg Brandl116aa622007-08-15 14:28:22 +00001731
1732The potential uses for metaclasses are boundless. Some ideas that have been
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001733explored include logging, interface checking, automatic delegation, automatic
Georg Brandl116aa622007-08-15 14:28:22 +00001734property creation, proxies, frameworks, and automatic resource
1735locking/synchronization.
1736
Raymond Hettinger15efcb62009-04-07 02:09:15 +00001737Here is an example of a metaclass that uses an :class:`collections.OrderedDict`
Raymond Hettingeraa7886d2014-05-26 22:20:37 -07001738to remember the order that class variables are defined::
Raymond Hettinger958e3682009-04-07 02:08:23 +00001739
1740 class OrderedClass(type):
1741
1742 @classmethod
1743 def __prepare__(metacls, name, bases, **kwds):
1744 return collections.OrderedDict()
1745
Nick Coghlan7fc570a2012-05-20 02:34:13 +10001746 def __new__(cls, name, bases, namespace, **kwds):
1747 result = type.__new__(cls, name, bases, dict(namespace))
1748 result.members = tuple(namespace)
Raymond Hettinger958e3682009-04-07 02:08:23 +00001749 return result
1750
1751 class A(metaclass=OrderedClass):
1752 def one(self): pass
1753 def two(self): pass
1754 def three(self): pass
1755 def four(self): pass
1756
1757 >>> A.members
1758 ('__module__', 'one', 'two', 'three', 'four')
1759
Raymond Hettingerc4faeea2009-04-07 02:31:14 +00001760When the class definition for *A* gets executed, the process begins with
1761calling the metaclass's :meth:`__prepare__` method which returns an empty
Raymond Hettinger958e3682009-04-07 02:08:23 +00001762:class:`collections.OrderedDict`. That mapping records the methods and
1763attributes of *A* as they are defined within the body of the class statement.
Raymond Hettingerc4faeea2009-04-07 02:31:14 +00001764Once those definitions are executed, the ordered dictionary is fully populated
Hirokazu Yamamotoae9eb5c2009-04-26 03:34:06 +00001765and the metaclass's :meth:`__new__` method gets invoked. That method builds
Raymond Hettingerc4faeea2009-04-07 02:31:14 +00001766the new type and it saves the ordered dictionary keys in an attribute
Fred Drake11c49a52010-11-13 04:24:26 +00001767called ``members``.
Raymond Hettinger958e3682009-04-07 02:08:23 +00001768
Georg Brandl116aa622007-08-15 14:28:22 +00001769
Georg Brandl8569e582010-05-19 20:57:08 +00001770Customizing instance and subclass checks
1771----------------------------------------
1772
1773The following methods are used to override the default behavior of the
1774:func:`isinstance` and :func:`issubclass` built-in functions.
1775
1776In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
1777order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
Benjamin Petersond7c3ed52010-06-27 22:32:30 +00001778classes" to any class or type (including built-in types), including other
Georg Brandl8569e582010-05-19 20:57:08 +00001779ABCs.
1780
1781.. method:: class.__instancecheck__(self, instance)
1782
1783 Return true if *instance* should be considered a (direct or indirect)
1784 instance of *class*. If defined, called to implement ``isinstance(instance,
1785 class)``.
1786
1787
1788.. method:: class.__subclasscheck__(self, subclass)
1789
1790 Return true if *subclass* should be considered a (direct or indirect)
1791 subclass of *class*. If defined, called to implement ``issubclass(subclass,
1792 class)``.
1793
1794
1795Note that these methods are looked up on the type (metaclass) of a class. They
1796cannot be defined as class methods in the actual class. This is consistent with
Benjamin Petersond7c3ed52010-06-27 22:32:30 +00001797the lookup of special methods that are called on instances, only in this
Georg Brandl8569e582010-05-19 20:57:08 +00001798case the instance is itself a class.
1799
1800.. seealso::
1801
1802 :pep:`3119` - Introducing Abstract Base Classes
1803 Includes the specification for customizing :func:`isinstance` and
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001804 :func:`issubclass` behavior through :meth:`~class.__instancecheck__` and
1805 :meth:`~class.__subclasscheck__`, with motivation for this functionality
1806 in the context of adding Abstract Base Classes (see the :mod:`abc`
1807 module) to the language.
Georg Brandl8569e582010-05-19 20:57:08 +00001808
1809
Georg Brandl116aa622007-08-15 14:28:22 +00001810.. _callable-types:
1811
1812Emulating callable objects
1813--------------------------
1814
1815
1816.. method:: object.__call__(self[, args...])
1817
1818 .. index:: pair: call; instance
1819
1820 Called when the instance is "called" as a function; if this method is defined,
1821 ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
1822
1823
1824.. _sequence-types:
1825
1826Emulating container types
1827-------------------------
1828
1829The following methods can be defined to implement container objects. Containers
1830usually are sequences (such as lists or tuples) or mappings (like dictionaries),
1831but can represent other containers as well. The first set of methods is used
1832either to emulate a sequence or to emulate a mapping; the difference is that for
1833a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
1834N`` where *N* is the length of the sequence, or slice objects, which define a
Georg Brandlcb8ecb12007-09-04 06:35:14 +00001835range of items. It is also recommended that mappings provide the methods
Georg Brandlc7723722008-05-26 17:47:11 +00001836:meth:`keys`, :meth:`values`, :meth:`items`, :meth:`get`, :meth:`clear`,
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001837:meth:`setdefault`, :meth:`pop`, :meth:`popitem`, :meth:`!copy`, and
Georg Brandlcb8ecb12007-09-04 06:35:14 +00001838:meth:`update` behaving similar to those for Python's standard dictionary
Serhiy Storchaka0d196ed2013-10-09 14:02:31 +03001839objects. The :mod:`collections` module provides a
1840:class:`~collections.abc.MutableMapping`
Georg Brandlc7723722008-05-26 17:47:11 +00001841abstract base class to help create those methods from a base set of
1842:meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and :meth:`keys`.
1843Mutable sequences should provide methods :meth:`append`, :meth:`count`,
1844:meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, :meth:`remove`,
1845:meth:`reverse` and :meth:`sort`, like Python standard list objects. Finally,
1846sequence types should implement addition (meaning concatenation) and
1847multiplication (meaning repetition) by defining the methods :meth:`__add__`,
1848:meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, :meth:`__rmul__` and
1849:meth:`__imul__` described below; they should not define other numerical
1850operators. It is recommended that both mappings and sequences implement the
1851:meth:`__contains__` method to allow efficient use of the ``in`` operator; for
1852mappings, ``in`` should search the mapping's keys; for sequences, it should
1853search through the values. It is further recommended that both mappings and
1854sequences implement the :meth:`__iter__` method to allow efficient iteration
1855through the container; for mappings, :meth:`__iter__` should be the same as
Fred Drake2e748782007-09-04 17:33:11 +00001856:meth:`keys`; for sequences, it should iterate through the values.
Georg Brandl116aa622007-08-15 14:28:22 +00001857
1858.. method:: object.__len__(self)
1859
1860 .. index::
1861 builtin: len
1862 single: __bool__() (object method)
1863
1864 Called to implement the built-in function :func:`len`. Should return the length
1865 of the object, an integer ``>=`` 0. Also, an object that doesn't define a
1866 :meth:`__bool__` method and whose :meth:`__len__` method returns zero is
1867 considered to be false in a Boolean context.
1868
1869
Armin Ronacher74b38b12012-10-07 10:29:32 +02001870.. method:: object.__length_hint__(self)
1871
Ezio Melottie12dc282012-10-07 12:09:36 +03001872 Called to implement :func:`operator.length_hint`. Should return an estimated
Armin Ronacher74b38b12012-10-07 10:29:32 +02001873 length for the object (which may be greater or less than the actual length).
1874 The length must be an integer ``>=`` 0. This method is purely an
1875 optimization and is never required for correctness.
1876
1877 .. versionadded:: 3.4
1878
Georg Brandlcb8ecb12007-09-04 06:35:14 +00001879.. note::
1880
1881 Slicing is done exclusively with the following three methods. A call like ::
1882
1883 a[1:2] = b
1884
1885 is translated to ::
1886
1887 a[slice(1, 2, None)] = b
1888
1889 and so forth. Missing slice items are always filled in with ``None``.
1890
1891
Georg Brandl116aa622007-08-15 14:28:22 +00001892.. method:: object.__getitem__(self, key)
1893
1894 .. index:: object: slice
1895
1896 Called to implement evaluation of ``self[key]``. For sequence types, the
1897 accepted keys should be integers and slice objects. Note that the special
1898 interpretation of negative indexes (if the class wishes to emulate a sequence
1899 type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
1900 type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
1901 for the sequence (after any special interpretation of negative values),
1902 :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
1903 in the container), :exc:`KeyError` should be raised.
1904
1905 .. note::
1906
1907 :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
1908 indexes to allow proper detection of the end of the sequence.
1909
1910
Terry Jan Reedyb67f6e22014-12-10 18:38:19 -05001911.. method:: object.__missing__(self, key)
1912
1913 Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses
1914 when key is not in the dictionary.
1915
1916
Georg Brandl116aa622007-08-15 14:28:22 +00001917.. method:: object.__setitem__(self, key, value)
1918
1919 Called to implement assignment to ``self[key]``. Same note as for
1920 :meth:`__getitem__`. This should only be implemented for mappings if the
1921 objects support changes to the values for keys, or if new keys can be added, or
1922 for sequences if elements can be replaced. The same exceptions should be raised
1923 for improper *key* values as for the :meth:`__getitem__` method.
1924
1925
1926.. method:: object.__delitem__(self, key)
1927
1928 Called to implement deletion of ``self[key]``. Same note as for
1929 :meth:`__getitem__`. This should only be implemented for mappings if the
1930 objects support removal of keys, or for sequences if elements can be removed
1931 from the sequence. The same exceptions should be raised for improper *key*
1932 values as for the :meth:`__getitem__` method.
1933
1934
1935.. method:: object.__iter__(self)
1936
1937 This method is called when an iterator is required for a container. This method
1938 should return a new iterator object that can iterate over all the objects in the
R David Murrayc9f5f2d2014-12-10 09:51:01 -05001939 container. For mappings, it should iterate over the keys of the container.
Georg Brandl116aa622007-08-15 14:28:22 +00001940
1941 Iterator objects also need to implement this method; they are required to return
1942 themselves. For more information on iterator objects, see :ref:`typeiter`.
1943
Christian Heimes7f044312008-01-06 17:05:40 +00001944
1945.. method:: object.__reversed__(self)
1946
Georg Brandl22b34312009-07-26 14:54:51 +00001947 Called (if present) by the :func:`reversed` built-in to implement
Christian Heimes7f044312008-01-06 17:05:40 +00001948 reverse iteration. It should return a new iterator object that iterates
1949 over all the objects in the container in reverse order.
1950
Georg Brandl8a1e4c42009-05-25 21:13:36 +00001951 If the :meth:`__reversed__` method is not provided, the :func:`reversed`
Georg Brandl22b34312009-07-26 14:54:51 +00001952 built-in will fall back to using the sequence protocol (:meth:`__len__` and
Georg Brandl8a1e4c42009-05-25 21:13:36 +00001953 :meth:`__getitem__`). Objects that support the sequence protocol should
1954 only provide :meth:`__reversed__` if they can provide an implementation
1955 that is more efficient than the one provided by :func:`reversed`.
Christian Heimes7f044312008-01-06 17:05:40 +00001956
1957
Georg Brandl116aa622007-08-15 14:28:22 +00001958The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
1959implemented as an iteration through a sequence. However, container objects can
1960supply the following special method with a more efficient implementation, which
1961also does not require the object be a sequence.
1962
Georg Brandl116aa622007-08-15 14:28:22 +00001963.. method:: object.__contains__(self, item)
1964
Georg Brandl495f7b52009-10-27 15:28:25 +00001965 Called to implement membership test operators. Should return true if *item*
1966 is in *self*, false otherwise. For mapping objects, this should consider the
1967 keys of the mapping rather than the values or the key-item pairs.
1968
1969 For objects that don't define :meth:`__contains__`, the membership test first
1970 tries iteration via :meth:`__iter__`, then the old sequence iteration
1971 protocol via :meth:`__getitem__`, see :ref:`this section in the language
1972 reference <membership-test-details>`.
Georg Brandl116aa622007-08-15 14:28:22 +00001973
1974
Georg Brandl116aa622007-08-15 14:28:22 +00001975.. _numeric-types:
1976
1977Emulating numeric types
1978-----------------------
1979
1980The following methods can be defined to emulate numeric objects. Methods
1981corresponding to operations that are not supported by the particular kind of
1982number implemented (e.g., bitwise operations for non-integral numbers) should be
1983left undefined.
1984
1985
1986.. method:: object.__add__(self, other)
1987 object.__sub__(self, other)
1988 object.__mul__(self, other)
Georg Brandlae55dc02008-09-06 17:43:49 +00001989 object.__truediv__(self, other)
Georg Brandl116aa622007-08-15 14:28:22 +00001990 object.__floordiv__(self, other)
1991 object.__mod__(self, other)
1992 object.__divmod__(self, other)
1993 object.__pow__(self, other[, modulo])
1994 object.__lshift__(self, other)
1995 object.__rshift__(self, other)
1996 object.__and__(self, other)
1997 object.__xor__(self, other)
1998 object.__or__(self, other)
1999
2000 .. index::
2001 builtin: divmod
2002 builtin: pow
2003 builtin: pow
2004
2005 These methods are called to implement the binary arithmetic operations (``+``,
Georg Brandlae55dc02008-09-06 17:43:49 +00002006 ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
Georg Brandl116aa622007-08-15 14:28:22 +00002007 ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression
Brett Cannon3a954da2008-08-14 05:59:39 +00002008 ``x + y``, where *x* is an instance of a class that has an :meth:`__add__`
Georg Brandl116aa622007-08-15 14:28:22 +00002009 method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the
2010 equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
Georg Brandlae55dc02008-09-06 17:43:49 +00002011 related to :meth:`__truediv__`. Note that :meth:`__pow__` should be defined
2012 to accept an optional third argument if the ternary version of the built-in
2013 :func:`pow` function is to be supported.
Georg Brandl116aa622007-08-15 14:28:22 +00002014
2015 If one of those methods does not support the operation with the supplied
2016 arguments, it should return ``NotImplemented``.
2017
2018
Georg Brandl116aa622007-08-15 14:28:22 +00002019.. method:: object.__radd__(self, other)
2020 object.__rsub__(self, other)
2021 object.__rmul__(self, other)
Georg Brandl116aa622007-08-15 14:28:22 +00002022 object.__rtruediv__(self, other)
2023 object.__rfloordiv__(self, other)
2024 object.__rmod__(self, other)
2025 object.__rdivmod__(self, other)
2026 object.__rpow__(self, other)
2027 object.__rlshift__(self, other)
2028 object.__rrshift__(self, other)
2029 object.__rand__(self, other)
2030 object.__rxor__(self, other)
2031 object.__ror__(self, other)
2032
2033 .. index::
2034 builtin: divmod
2035 builtin: pow
2036
2037 These methods are called to implement the binary arithmetic operations (``+``,
Georg Brandlae55dc02008-09-06 17:43:49 +00002038 ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``,
2039 ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected (swapped) operands.
2040 These functions are only called if the left operand does not support the
2041 corresponding operation and the operands are of different types. [#]_ For
2042 instance, to evaluate the expression ``x - y``, where *y* is an instance of
2043 a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if
2044 ``x.__sub__(y)`` returns *NotImplemented*.
Georg Brandl116aa622007-08-15 14:28:22 +00002045
2046 .. index:: builtin: pow
2047
2048 Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
2049 coercion rules would become too complicated).
2050
2051 .. note::
2052
2053 If the right operand's type is a subclass of the left operand's type and that
2054 subclass provides the reflected method for the operation, this method will be
2055 called before the left operand's non-reflected method. This behavior allows
2056 subclasses to override their ancestors' operations.
2057
2058
2059.. method:: object.__iadd__(self, other)
2060 object.__isub__(self, other)
2061 object.__imul__(self, other)
Georg Brandl116aa622007-08-15 14:28:22 +00002062 object.__itruediv__(self, other)
2063 object.__ifloordiv__(self, other)
2064 object.__imod__(self, other)
2065 object.__ipow__(self, other[, modulo])
2066 object.__ilshift__(self, other)
2067 object.__irshift__(self, other)
2068 object.__iand__(self, other)
2069 object.__ixor__(self, other)
2070 object.__ior__(self, other)
2071
Benjamin Petersonb58dda72009-01-18 22:27:04 +00002072 These methods are called to implement the augmented arithmetic assignments
Georg Brandl116aa622007-08-15 14:28:22 +00002073 (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
2074 ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
2075 in-place (modifying *self*) and return the result (which could be, but does
2076 not have to be, *self*). If a specific method is not defined, the augmented
Larry Hastings3732ed22014-03-15 21:13:56 -07002077 assignment falls back to the normal methods. For instance, if *x* is an
2078 instance of a class with an :meth:`__iadd__` method, ``x += y`` is equivalent
2079 to ``x = x.__iadd__(y)`` . Otherwise, ``x.__add__(y)`` and ``y.__radd__(x)``
2080 are considered, as with the evaluation of ``x + y``. In certain situations,
2081 augmented assignment can result in unexpected errors (see
2082 :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in
2083 fact part of the data model.
Georg Brandl116aa622007-08-15 14:28:22 +00002084
2085
2086.. method:: object.__neg__(self)
2087 object.__pos__(self)
2088 object.__abs__(self)
2089 object.__invert__(self)
2090
2091 .. index:: builtin: abs
2092
2093 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
2094 and ``~``).
2095
2096
2097.. method:: object.__complex__(self)
2098 object.__int__(self)
Georg Brandl116aa622007-08-15 14:28:22 +00002099 object.__float__(self)
Mark Summerfield9557f602008-07-01 14:42:30 +00002100 object.__round__(self, [,n])
Georg Brandl116aa622007-08-15 14:28:22 +00002101
2102 .. index::
2103 builtin: complex
2104 builtin: int
Georg Brandl116aa622007-08-15 14:28:22 +00002105 builtin: float
Mark Summerfield9557f602008-07-01 14:42:30 +00002106 builtin: round
Georg Brandl116aa622007-08-15 14:28:22 +00002107
Mark Summerfield9557f602008-07-01 14:42:30 +00002108 Called to implement the built-in functions :func:`complex`,
2109 :func:`int`, :func:`float` and :func:`round`. Should return a value
2110 of the appropriate type.
Georg Brandl116aa622007-08-15 14:28:22 +00002111
2112
2113.. method:: object.__index__(self)
2114
Ethan Furmandf3ed242014-01-05 06:50:30 -08002115 Called to implement :func:`operator.index`, and whenever Python needs to
2116 losslessly convert the numeric object to an integer object (such as in
2117 slicing, or in the built-in :func:`bin`, :func:`hex` and :func:`oct`
2118 functions). Presence of this method indicates that the numeric object is
2119 an integer type. Must return an integer.
2120
2121 .. note::
2122
R David Murray2c078182014-06-05 15:31:56 -04002123 In order to have a coherent integer type class, when :meth:`__index__` is
2124 defined :meth:`__int__` should also be defined, and both should return
2125 the same value.
Georg Brandl116aa622007-08-15 14:28:22 +00002126
Georg Brandl116aa622007-08-15 14:28:22 +00002127
2128.. _context-managers:
2129
2130With Statement Context Managers
2131-------------------------------
2132
Georg Brandl116aa622007-08-15 14:28:22 +00002133A :dfn:`context manager` is an object that defines the runtime context to be
2134established when executing a :keyword:`with` statement. The context manager
2135handles the entry into, and the exit from, the desired runtime context for the
2136execution of the block of code. Context managers are normally invoked using the
2137:keyword:`with` statement (described in section :ref:`with`), but can also be
2138used by directly invoking their methods.
2139
2140.. index::
2141 statement: with
2142 single: context manager
2143
2144Typical uses of context managers include saving and restoring various kinds of
2145global state, locking and unlocking resources, closing opened files, etc.
2146
2147For more information on context managers, see :ref:`typecontextmanager`.
2148
2149
2150.. method:: object.__enter__(self)
2151
2152 Enter the runtime context related to this object. The :keyword:`with` statement
2153 will bind this method's return value to the target(s) specified in the
2154 :keyword:`as` clause of the statement, if any.
2155
2156
2157.. method:: object.__exit__(self, exc_type, exc_value, traceback)
2158
2159 Exit the runtime context related to this object. The parameters describe the
2160 exception that caused the context to be exited. If the context was exited
2161 without an exception, all three arguments will be :const:`None`.
2162
2163 If an exception is supplied, and the method wishes to suppress the exception
2164 (i.e., prevent it from being propagated), it should return a true value.
2165 Otherwise, the exception will be processed normally upon exit from this method.
2166
2167 Note that :meth:`__exit__` methods should not reraise the passed-in exception;
2168 this is the caller's responsibility.
2169
2170
2171.. seealso::
2172
2173 :pep:`0343` - The "with" statement
2174 The specification, background, and examples for the Python :keyword:`with`
2175 statement.
2176
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002177
2178.. _special-lookup:
2179
2180Special method lookup
2181---------------------
2182
2183For custom classes, implicit invocations of special methods are only guaranteed
2184to work correctly if defined on an object's type, not in the object's instance
2185dictionary. That behaviour is the reason why the following code raises an
2186exception::
2187
Éric Araujo28053fb2010-11-22 03:09:19 +00002188 >>> class C:
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002189 ... pass
2190 ...
2191 >>> c = C()
2192 >>> c.__len__ = lambda: 5
2193 >>> len(c)
2194 Traceback (most recent call last):
2195 File "<stdin>", line 1, in <module>
2196 TypeError: object of type 'C' has no len()
2197
2198The rationale behind this behaviour lies with a number of special methods such
2199as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects,
2200including type objects. If the implicit lookup of these methods used the
2201conventional lookup process, they would fail when invoked on the type object
2202itself::
2203
2204 >>> 1 .__hash__() == hash(1)
2205 True
2206 >>> int.__hash__() == hash(int)
2207 Traceback (most recent call last):
2208 File "<stdin>", line 1, in <module>
2209 TypeError: descriptor '__hash__' of 'int' object needs an argument
2210
2211Incorrectly attempting to invoke an unbound method of a class in this way is
2212sometimes referred to as 'metaclass confusion', and is avoided by bypassing
2213the instance when looking up special methods::
2214
2215 >>> type(1).__hash__(1) == hash(1)
2216 True
2217 >>> type(int).__hash__(int) == hash(int)
2218 True
2219
2220In addition to bypassing any instance attributes in the interest of
Georg Brandlaf265f42008-12-07 15:06:20 +00002221correctness, implicit special method lookup generally also bypasses the
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002222:meth:`__getattribute__` method even of the object's metaclass::
2223
2224 >>> class Meta(type):
Berker Peksag770319d2015-04-11 14:59:30 +03002225 ... def __getattribute__(*args):
2226 ... print("Metaclass getattribute invoked")
2227 ... return type.__getattribute__(*args)
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002228 ...
Benjamin Petersone348d1a2008-10-19 21:29:05 +00002229 >>> class C(object, metaclass=Meta):
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002230 ... def __len__(self):
2231 ... return 10
2232 ... def __getattribute__(*args):
Benjamin Peterson64106fb2008-10-29 20:35:35 +00002233 ... print("Class getattribute invoked")
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002234 ... return object.__getattribute__(*args)
2235 ...
2236 >>> c = C()
2237 >>> c.__len__() # Explicit lookup via instance
2238 Class getattribute invoked
2239 10
2240 >>> type(c).__len__(c) # Explicit lookup via type
2241 Metaclass getattribute invoked
2242 10
2243 >>> len(c) # Implicit lookup
2244 10
2245
2246Bypassing the :meth:`__getattribute__` machinery in this fashion
2247provides significant scope for speed optimisations within the
2248interpreter, at the cost of some flexibility in the handling of
2249special methods (the special method *must* be set on the class
2250object itself in order to be consistently invoked by the interpreter).
2251
2252
Georg Brandl116aa622007-08-15 14:28:22 +00002253.. rubric:: Footnotes
2254
Nick Coghlan3a5d7e32008-08-31 12:40:14 +00002255.. [#] It *is* possible in some cases to change an object's type, under certain
2256 controlled conditions. It generally isn't a good idea though, since it can
2257 lead to some very strange behaviour if it is handled incorrectly.
2258
Georg Brandl116aa622007-08-15 14:28:22 +00002259.. [#] For operands of the same type, it is assumed that if the non-reflected method
2260 (such as :meth:`__add__`) fails the operation is not supported, which is why the
2261 reflected method is not called.