GNU Info

(python2.1-ref.info)Emulating sequence and mapping types

---

Next: Additional methods for emulation of sequence types Prev: Emulating callable objects Up: Special method names

---

Enter node , (file) or (file)node

Emulating sequence and mapping types
------------------------------------

The following methods can be defined to emulate sequence or mapping
objects.  The first set of methods is used either to emulate a sequence
or to emulate a mapping; the difference is that for a sequence, the
allowable keys should be the integers K for which `0 <= K < N' where N
is the length of the sequence, or slice objects, which define a range
of items. (For backwards compatibility, the method `__getslice__()'
(see below) can also be defined to handle simple, but not extended
slices.) It is also recommended that mappings provide the methods
`keys()', `values()', `items()', `has_key()', `get()', `clear()',
`copy()', and `update()' behaving similar to those for Python's
standard dictionary objects; mutable sequences should provide methods
`append()', `count()', `index()', `insert()', `pop()', `remove()',
`reverse()' and `sort()', like Python standard list objects.  Finally,
sequence types should implement addition (meaning concatenation) and
multiplication (meaning repetition) by defining the methods
`__add__()', `__radd__()', `__iadd__()', `__mul__()', `__rmul__()' and
`__imul__()' described below; they should not define `__coerce__()' or
other numerical operators.  It is recommended that both mappings and
sequences implement the `__contains__', to allow efficient use of the
`in' operator; for mappings, `in' should be equivalent of `has_key()';
for sequences, it should search through the values.

`__len__(self)'
     Called to implement the built-in function `len()' .  Should return
     the length of the object, an integer `>=' 0.  Also, an object that
     doesn't define a `__nonzero__()' method and whose `__len__()'
     method returns zero is considered to be false in a Boolean context.

`__getitem__(self, key)'
     Called to implement evaluation of `SELF[KEY]'.  For sequence
     types, the accepted keys should be integers and slice objects.
     Note that the special interpretation of negative indexes (if the
     class wishes to emulate a sequence type) is up to the
     `__getitem__()' method.  If KEY is of an inappropriate type,
     `TypeError' may be raised; if of a value outside the set of
     indexes for the sequence (after any special interpretation of
     negative values), `IndexError' should be raised.  *Note:*  `for'
     loops expect that an `IndexError' will be raised for illegal
     indexes to allow proper detection of the end of the sequence.

`__setitem__(self, key, value)'
     Called to implement assignment to `SELF[KEY]'.  Same note as for
     `__getitem__()'.  This should only be implemented for mappings if
     the objects support changes to the values for keys, or if new keys
     can be added, or for sequences if elements can be replaced.  The
     same exceptions should be raised for improper KEY values as for
     the `__getitem__()' method.

`__delitem__(self, key)'
     Called to implement deletion of `SELF[KEY]'.  Same note as for
     `__getitem__()'.  This should only be implemented for mappings if
     the objects support removal of keys, or for sequences if elements
     can be removed from the sequence.  The same exceptions should be
     raised for improper KEY values as for the `__getitem__()' method.