Doc/library/collections.rst

   1
   2 :mod:`collections` --- High-performance container datatypes
   3 ===========================================================
   4
   5 .. module:: collections
   6    :synopsis: High-performance datatypes
   7 .. moduleauthor:: Raymond Hettinger <python@rcn.com>
   8 .. sectionauthor:: Raymond Hettinger <python@rcn.com>
   9
  10 .. versionadded:: 2.4
  11
  12 .. testsetup:: *
  13
  14    from collections import *
  15    import itertools
  16    __name__ = '<doctest>'
  17
  18 This module implements high-performance container datatypes.  Currently,
  19 there are two datatypes, :class:`deque` and :class:`defaultdict`, and
  20 one datatype factory function, :func:`namedtuple`.
  21
  22 .. versionchanged:: 2.5
  23    Added :class:`defaultdict`.
  24
  25 .. versionchanged:: 2.6
  26    Added :func:`namedtuple`.
  27
  28 The specialized containers provided in this module provide alternatives
  29 to Python's general purpose built-in containers, :class:`dict`,
  30 :class:`list`, :class:`set`, and :class:`tuple`.
  31
  32 Besides the containers provided here, the optional :mod:`bsddb`
  33 module offers the ability to create in-memory or file based ordered
  34 dictionaries with string keys using the :meth:`bsddb.btopen` method.
  35
  36 In addition to containers, the collections module provides some ABCs
  37 (abstract base classes) that can be used to test whether a class
  38 provides a particular interface, for example, is it hashable or
  39 a mapping.
  40
  41 .. versionchanged:: 2.6
  42    Added abstract base classes.
  43
  44 ABCs - abstract base classes
  45 ----------------------------
  46
  47 The collections module offers the following ABCs:
  48
  49 =========================  =====================  ======================  ====================================================
  50 ABC                        Inherits               Abstract Methods        Mixin Methods
  51 =========================  =====================  ======================  ====================================================
  52 :class:`Container`                                ``__contains__``
  53 :class:`Hashable`                                 ``__hash__``
  54 :class:`Iterable`                                 ``__iter__``
  55 :class:`Iterator`          :class:`Iterable`      ``__next__``            ``__iter__``
  56 :class:`Sized`                                    ``__len__``
  57 :class:`Callable`                                 ``__call__``
  58
  59 :class:`Sequence`          :class:`Sized`,        ``__getitem__``         ``__contains__``. ``__iter__``, ``__reversed__``.
  60                            :class:`Iterable`,     and ``__len__``         ``index``, and ``count``
  61                            :class:`Container`
  62
  63 :class:`MutableSequence`   :class:`Sequence`      ``__getitem__``         Inherited Sequence methods and
  64                                                   ``__delitem__``,        ``append``, ``reverse``, ``extend``, ``pop``,
  65                                                   ``insert``,             ``remove``, and ``__iadd__``
  66                                                   and ``__len__``
  67
  68 :class:`Set`               :class:`Sized`,        ``__len__``,            ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
  69                            :class:`Iterable`,     ``__iter__``, and       ``__gt__``, ``__ge__``, ``__and__``, ``__or__``
  70                            :class:`Container`     ``__contains__``        ``__sub__``, ``__xor__``, and ``isdisjoint``
  71
  72 :class:`MutableSet`        :class:`Set`           ``add`` and             Inherited Set methods and
  73                                                   ``discard``             ``clear``, ``pop``, ``remove``, ``__ior__``,
  74                                                                           ``__iand__``, ``__ixor__``, and ``__isub__``
  75
  76 :class:`Mapping`           :class:`Sized`,        ``__getitem__``,        ``__contains__``, ``keys``, ``items``, ``values``,
  77                            :class:`Iterable`,     ``__len__``. and        ``get``, ``__eq__``, and ``__ne__``
  78                            :class:`Container`     ``__iter__``
  79
  80 :class:`MutableMapping`    :class:`Mapping`       ``__getitem__``         Inherited Mapping methods and
  81                                                   ``__setitem__``,        ``pop``, ``popitem``, ``clear``, ``update``,
  82                                                   ``__delitem__``,        and ``setdefault``
  83                                                   ``__iter__``, and
  84                                                   ``__len__``
  85
  86 :class:`MappingView`       :class:`Sized`                                 ``__len__``
  87 :class:`KeysView`          :class:`MappingView`,                          ``__contains__``,
  88                            :class:`Set`                                   ``__iter__``
  89 :class:`ItemsView`         :class:`MappingView`,                          ``__contains__``,
  90                            :class:`Set`                                   ``__iter__``
  91 :class:`ValuesView`        :class:`MappingView`                           ``__contains__``, ``__iter__``
  92 =========================  =====================  ======================  ====================================================
  93
  94 These ABCs allow us to ask classes or instances if they provide
  95 particular functionality, for example::
  96
  97     size = None
  98     if isinstance(myvar, collections.Sized):
  99         size = len(myvar)
 100
 101 Several of the ABCs are also useful as mixins that make it easier to develop
 102 classes supporting container APIs.  For example, to write a class supporting
 103 the full :class:`Set` API, it only necessary to supply the three underlying
 104 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
 105 The ABC supplies the remaining methods such as :meth:`__and__` and
 106 :meth:`isdisjoint` ::
 107
 108     class ListBasedSet(collections.Set):
 109          ''' Alternate set implementation favoring space over speed
 110              and not requiring the set elements to be hashable. '''
 111          def __init__(self, iterable):
 112              self.elements = lst = []
 113              for value in iterable:
 114                  if value not in lst:
 115                      lst.append(value)
 116          def __iter__(self):
 117              return iter(self.elements)
 118          def __contains__(self, value):
 119              return value in self.elements
 120          def __len__(self):
 121              return len(self.elements)
 122
 123     s1 = ListBasedSet('abcdef')
 124     s2 = ListBasedSet('defghi')
 125     overlap = s1 & s2            # The __and__() method is supported automatically
 126
 127 Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
 128
 129 (1)
 130    Since some set operations create new sets, the default mixin methods need
 131    a way to create new instances from an iterable. The class constructor is
 132    assumed to have a signature in the form ``ClassName(iterable)``.
 133    That assumption is factored-out to an internal classmethod called
 134    :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
 135    If the :class:`Set` mixin is being used in a class with a different
 136    constructor signature, you will need to override :meth:`from_iterable`
 137    with a classmethod that can construct new instances from
 138    an iterable argument.
 139
 140 (2)
 141    To override the comparisons (presumably for speed, as the
 142    semantics are fixed), redefine :meth:`__le__` and
 143    then the other operations will automatically follow suit.
 144
 145 (3)
 146    The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
 147    for the set; however, :meth:`__hash__` is not defined because not all sets
 148    are hashable or immutable.  To add set hashabilty using mixins,
 149    inherit from both :meth:`Set` and :meth:`Hashable`, then define
 150    ``__hash__ = Set._hash``.
 151
 152 (For more about ABCs, see the :mod:`abc` module and :pep:`3119`.)
 153
 154
 155
 156 .. _deque-objects:
 157
 158 :class:`deque` objects
 159 ----------------------
 160
 161
 162 .. class:: deque([iterable[, maxlen]])
 163
 164    Returns a new deque object initialized left-to-right (using :meth:`append`) with
 165    data from *iterable*.  If *iterable* is not specified, the new deque is empty.
 166
 167    Deques are a generalization of stacks and queues (the name is pronounced "deck"
 168    and is short for "double-ended queue").  Deques support thread-safe, memory
 169    efficient appends and pops from either side of the deque with approximately the
 170    same O(1) performance in either direction.
 171
 172    Though :class:`list` objects support similar operations, they are optimized for
 173    fast fixed-length operations and incur O(n) memory movement costs for
 174    ``pop(0)`` and ``insert(0, v)`` operations which change both the size and
 175    position of the underlying data representation.
 176
 177    .. versionadded:: 2.4
 178
 179    If *maxlen* is not specified or is *None*, deques may grow to an
 180    arbitrary length.  Otherwise, the deque is bounded to the specified maximum
 181    length.  Once a bounded length deque is full, when new items are added, a
 182    corresponding number of items are discarded from the opposite end.  Bounded
 183    length deques provide functionality similar to the ``tail`` filter in
 184    Unix. They are also useful for tracking transactions and other pools of data
 185    where only the most recent activity is of interest.
 186
 187    .. versionchanged:: 2.6
 188       Added *maxlen* parameter.
 189
 190    Deque objects support the following methods:
 191
 192
 193    .. method:: append(x)
 194
 195       Add *x* to the right side of the deque.
 196
 197
 198    .. method:: appendleft(x)
 199
 200       Add *x* to the left side of the deque.
 201
 202
 203    .. method:: clear()
 204
 205       Remove all elements from the deque leaving it with length 0.
 206
 207
 208    .. method:: extend(iterable)
 209
 210       Extend the right side of the deque by appending elements from the iterable
 211       argument.
 212
 213
 214    .. method:: extendleft(iterable)
 215
 216       Extend the left side of the deque by appending elements from *iterable*.
 217       Note, the series of left appends results in reversing the order of
 218       elements in the iterable argument.
 219
 220
 221    .. method:: pop()
 222
 223       Remove and return an element from the right side of the deque. If no
 224       elements are present, raises an :exc:`IndexError`.
 225
 226
 227    .. method:: popleft()
 228
 229       Remove and return an element from the left side of the deque. If no
 230       elements are present, raises an :exc:`IndexError`.
 231
 232
 233    .. method:: remove(value)
 234
 235       Removed the first occurrence of *value*.  If not found, raises a
 236       :exc:`ValueError`.
 237
 238       .. versionadded:: 2.5
 239
 240
 241    .. method:: rotate(n)
 242
 243       Rotate the deque *n* steps to the right.  If *n* is negative, rotate to
 244       the left.  Rotating one step to the right is equivalent to:
 245       ``d.appendleft(d.pop())``.
 246
 247
 248 In addition to the above, deques support iteration, pickling, ``len(d)``,
 249 ``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
 250 the :keyword:`in` operator, and subscript references such as ``d[-1]``.  Indexed
 251 access is O(1) at both ends but slows to O(n) in the middle.  For fast random
 252 access, use lists instead.
 253
 254 Example:
 255
 256 .. doctest::
 257
 258    >>> from collections import deque
 259    >>> d = deque('ghi')                 # make a new deque with three items
 260    >>> for elem in d:                   # iterate over the deque's elements
 261    ...     print elem.upper()
 262    G
 263    H
 264    I
 265
 266    >>> d.append('j')                    # add a new entry to the right side
 267    >>> d.appendleft('f')                # add a new entry to the left side
 268    >>> d                                # show the representation of the deque
 269    deque(['f', 'g', 'h', 'i', 'j'])
 270
 271    >>> d.pop()                          # return and remove the rightmost item
 272    'j'
 273    >>> d.popleft()                      # return and remove the leftmost item
 274    'f'
 275    >>> list(d)                          # list the contents of the deque
 276    ['g', 'h', 'i']
 277    >>> d[0]                             # peek at leftmost item
 278    'g'
 279    >>> d[-1]                            # peek at rightmost item
 280    'i'
 281
 282    >>> list(reversed(d))                # list the contents of a deque in reverse
 283    ['i', 'h', 'g']
 284    >>> 'h' in d                         # search the deque
 285    True
 286    >>> d.extend('jkl')                  # add multiple elements at once
 287    >>> d
 288    deque(['g', 'h', 'i', 'j', 'k', 'l'])
 289    >>> d.rotate(1)                      # right rotation
 290    >>> d
 291    deque(['l', 'g', 'h', 'i', 'j', 'k'])
 292    >>> d.rotate(-1)                     # left rotation
 293    >>> d
 294    deque(['g', 'h', 'i', 'j', 'k', 'l'])
 295
 296    >>> deque(reversed(d))               # make a new deque in reverse order
 297    deque(['l', 'k', 'j', 'i', 'h', 'g'])
 298    >>> d.clear()                        # empty the deque
 299    >>> d.pop()                          # cannot pop from an empty deque
 300    Traceback (most recent call last):
 301      File "<pyshell#6>", line 1, in -toplevel-
 302        d.pop()
 303    IndexError: pop from an empty deque
 304
 305    >>> d.extendleft('abc')              # extendleft() reverses the input order
 306    >>> d
 307    deque(['c', 'b', 'a'])
 308
 309
 310 .. _deque-recipes:
 311
 312 :class:`deque` Recipes
 313 ^^^^^^^^^^^^^^^^^^^^^^
 314
 315 This section shows various approaches to working with deques.
 316
 317 The :meth:`rotate` method provides a way to implement :class:`deque` slicing and
 318 deletion.  For example, a pure python implementation of ``del d[n]`` relies on
 319 the :meth:`rotate` method to position elements to be popped::
 320
 321    def delete_nth(d, n):
 322        d.rotate(-n)
 323        d.popleft()
 324        d.rotate(n)
 325
 326 To implement :class:`deque` slicing, use a similar approach applying
 327 :meth:`rotate` to bring a target element to the left side of the deque. Remove
 328 old entries with :meth:`popleft`, add new entries with :meth:`extend`, and then
 329 reverse the rotation.
 330 With minor variations on that approach, it is easy to implement Forth style
 331 stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
 332 ``rot``, and ``roll``.
 333
 334 Multi-pass data reduction algorithms can be succinctly expressed and efficiently
 335 coded by extracting elements with multiple calls to :meth:`popleft`, applying
 336 a reduction function, and calling :meth:`append` to add the result back to the
 337 deque.
 338
 339 For example, building a balanced binary tree of nested lists entails reducing
 340 two adjacent nodes into one by grouping them in a list:
 341
 342    >>> def maketree(iterable):
 343    ...     d = deque(iterable)
 344    ...     while len(d) > 1:
 345    ...         pair = [d.popleft(), d.popleft()]
 346    ...         d.append(pair)
 347    ...     return list(d)
 348    ...
 349    >>> print maketree('abcdefgh')
 350    [[[['a', 'b'], ['c', 'd']], [['e', 'f'], ['g', 'h']]]]
 351
 352 Bounded length deques provide functionality similar to the ``tail`` filter
 353 in Unix::
 354
 355    def tail(filename, n=10):
 356        'Return the last n lines of a file'
 357        return deque(open(filename), n)
 358
 359 .. _defaultdict-objects:
 360
 361 :class:`defaultdict` objects
 362 ----------------------------
 363
 364
 365 .. class:: defaultdict([default_factory[, ...]])
 366
 367    Returns a new dictionary-like object.  :class:`defaultdict` is a subclass of the
 368    builtin :class:`dict` class.  It overrides one method and adds one writable
 369    instance variable.  The remaining functionality is the same as for the
 370    :class:`dict` class and is not documented here.
 371
 372    The first argument provides the initial value for the :attr:`default_factory`
 373    attribute; it defaults to ``None``. All remaining arguments are treated the same
 374    as if they were passed to the :class:`dict` constructor, including keyword
 375    arguments.
 376
 377    .. versionadded:: 2.5
 378
 379    :class:`defaultdict` objects support the following method in addition to the
 380    standard :class:`dict` operations:
 381
 382
 383    .. method:: defaultdict.__missing__(key)
 384
 385       If the :attr:`default_factory` attribute is ``None``, this raises a
 386       :exc:`KeyError` exception with the *key* as argument.
 387
 388       If :attr:`default_factory` is not ``None``, it is called without arguments
 389       to provide a default value for the given *key*, this value is inserted in
 390       the dictionary for the *key*, and returned.
 391
 392       If calling :attr:`default_factory` raises an exception this exception is
 393       propagated unchanged.
 394
 395       This method is called by the :meth:`__getitem__` method of the
 396       :class:`dict` class when the requested key is not found; whatever it
 397       returns or raises is then returned or raised by :meth:`__getitem__`.
 398
 399
 400    :class:`defaultdict` objects support the following instance variable:
 401
 402
 403    .. attribute:: defaultdict.default_factory
 404
 405       This attribute is used by the :meth:`__missing__` method; it is
 406       initialized from the first argument to the constructor, if present, or to
 407       ``None``, if absent.
 408
 409
 410 .. _defaultdict-examples:
 411
 412 :class:`defaultdict` Examples
 413 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 414
 415 Using :class:`list` as the :attr:`default_factory`, it is easy to group a
 416 sequence of key-value pairs into a dictionary of lists:
 417
 418    >>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
 419    >>> d = defaultdict(list)
 420    >>> for k, v in s:
 421    ...     d[k].append(v)
 422    ...
 423    >>> d.items()
 424    [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
 425
 426 When each key is encountered for the first time, it is not already in the
 427 mapping; so an entry is automatically created using the :attr:`default_factory`
 428 function which returns an empty :class:`list`.  The :meth:`list.append`
 429 operation then attaches the value to the new list.  When keys are encountered
 430 again, the look-up proceeds normally (returning the list for that key) and the
 431 :meth:`list.append` operation adds another value to the list. This technique is
 432 simpler and faster than an equivalent technique using :meth:`dict.setdefault`:
 433
 434    >>> d = {}
 435    >>> for k, v in s:
 436    ...     d.setdefault(k, []).append(v)
 437    ...
 438    >>> d.items()
 439    [('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
 440
 441 Setting the :attr:`default_factory` to :class:`int` makes the
 442 :class:`defaultdict` useful for counting (like a bag or multiset in other
 443 languages):
 444
 445    >>> s = 'mississippi'
 446    >>> d = defaultdict(int)
 447    >>> for k in s:
 448    ...     d[k] += 1
 449    ...
 450    >>> d.items()
 451    [('i', 4), ('p', 2), ('s', 4), ('m', 1)]
 452
 453 When a letter is first encountered, it is missing from the mapping, so the
 454 :attr:`default_factory` function calls :func:`int` to supply a default count of
 455 zero.  The increment operation then builds up the count for each letter.
 456
 457 The function :func:`int` which always returns zero is just a special case of
 458 constant functions.  A faster and more flexible way to create constant functions
 459 is to use :func:`itertools.repeat` which can supply any constant value (not just
 460 zero):
 461
 462    >>> def constant_factory(value):
 463    ...     return itertools.repeat(value).next
 464    >>> d = defaultdict(constant_factory('<missing>'))
 465    >>> d.update(name='John', action='ran')
 466    >>> '%(name)s %(action)s to %(object)s' % d
 467    'John ran to <missing>'
 468
 469 Setting the :attr:`default_factory` to :class:`set` makes the
 470 :class:`defaultdict` useful for building a dictionary of sets:
 471
 472    >>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
 473    >>> d = defaultdict(set)
 474    >>> for k, v in s:
 475    ...     d[k].add(v)
 476    ...
 477    >>> d.items()
 478    [('blue', set([2, 4])), ('red', set([1, 3]))]
 479
 480
 481 .. _named-tuple-factory:
 482
 483 :func:`namedtuple` Factory Function for Tuples with Named Fields
 484 ----------------------------------------------------------------
 485
 486 Named tuples assign meaning to each position in a tuple and allow for more readable,
 487 self-documenting code.  They can be used wherever regular tuples are used, and
 488 they add the ability to access fields by name instead of position index.
 489
 490 .. function:: namedtuple(typename, field_names, [verbose])
 491
 492    Returns a new tuple subclass named *typename*.  The new subclass is used to
 493    create tuple-like objects that have fields accessible by attribute lookup as
 494    well as being indexable and iterable.  Instances of the subclass also have a
 495    helpful docstring (with typename and field_names) and a helpful :meth:`__repr__`
 496    method which lists the tuple contents in a ``name=value`` format.
 497
 498    The *field_names* are a single string with each fieldname separated by whitespace
 499    and/or commas, for example ``'x y'`` or ``'x, y'``.  Alternatively, *field_names*
 500    can be a sequence of strings such as ``['x', 'y']``.
 501
 502    Any valid Python identifier may be used for a fieldname except for names
 503    starting with an underscore.  Valid identifiers consist of letters, digits,
 504    and underscores but do not start with a digit or underscore and cannot be
 505    a :mod:`keyword` such as *class*, *for*, *return*, *global*, *pass*, *print*,
 506    or *raise*.
 507
 508    If *verbose* is true, the class definition is printed just before being built.
 509
 510    Named tuple instances do not have per-instance dictionaries, so they are
 511    lightweight and require no more memory than regular tuples.
 512
 513    .. versionadded:: 2.6
 514
 515 Example:
 516
 517 .. doctest::
 518    :options: +NORMALIZE_WHITESPACE
 519
 520    >>> Point = namedtuple('Point', 'x y', verbose=True)
 521    class Point(tuple):
 522            'Point(x, y)'
 523    <BLANKLINE>
 524            __slots__ = ()
 525    <BLANKLINE>
 526            _fields = ('x', 'y')
 527    <BLANKLINE>
 528            def __new__(cls, x, y):
 529                return tuple.__new__(cls, (x, y))
 530    <BLANKLINE>
 531            @classmethod
 532            def _make(cls, iterable, new=tuple.__new__, len=len):
 533                'Make a new Point object from a sequence or iterable'
 534                result = new(cls, iterable)
 535                if len(result) != 2:
 536                    raise TypeError('Expected 2 arguments, got %d' % len(result))
 537                return result
 538    <BLANKLINE>
 539            def __repr__(self):
 540                return 'Point(x=%r, y=%r)' % self
 541    <BLANKLINE>
 542            def _asdict(t):
 543                'Return a new dict which maps field names to their values'
 544                return {'x': t[0], 'y': t[1]}
 545    <BLANKLINE>
 546            def _replace(self, **kwds):
 547                'Return a new Point object replacing specified fields with new values'
 548                result = self._make(map(kwds.pop, ('x', 'y'), self))
 549                if kwds:
 550                    raise ValueError('Got unexpected field names: %r' % kwds.keys())
 551                return result
 552    <BLANKLINE>
 553            def __getnewargs__(self):
 554                return tuple(self)
 555    <BLANKLINE>
 556            x = property(itemgetter(0))
 557            y = property(itemgetter(1))
 558
 559    >>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
 560    >>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
 561    33
 562    >>> x, y = p                # unpack like a regular tuple
 563    >>> x, y
 564    (11, 22)
 565    >>> p.x + p.y               # fields also accessible by name
 566    33
 567    >>> p                       # readable __repr__ with a name=value style
 568    Point(x=11, y=22)
 569
 570 Named tuples are especially useful for assigning field names to result tuples returned
 571 by the :mod:`csv` or :mod:`sqlite3` modules::
 572
 573    EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')
 574
 575    import csv
 576    for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
 577        print emp.name, emp.title
 578
 579    import sqlite3
 580    conn = sqlite3.connect('/companydata')
 581    cursor = conn.cursor()
 582    cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
 583    for emp in map(EmployeeRecord._make, cursor.fetchall()):
 584        print emp.name, emp.title
 585
 586 In addition to the methods inherited from tuples, named tuples support
 587 three additional methods and one attribute.  To prevent conflicts with
 588 field names, the method and attribute names start with an underscore.
 589
 590 .. method:: somenamedtuple._make(iterable)
 591
 592    Class method that makes a new instance from an existing sequence or iterable.
 593
 594 .. doctest::
 595
 596       >>> t = [11, 22]
 597       >>> Point._make(t)
 598       Point(x=11, y=22)
 599
 600 .. method:: somenamedtuple._asdict()
 601
 602    Return a new dict which maps field names to their corresponding values::
 603
 604       >>> p._asdict()
 605       {'x': 11, 'y': 22}
 606
 607 .. method:: somenamedtuple._replace(kwargs)
 608
 609    Return a new instance of the named tuple replacing specified fields with new
 610    values:
 611
 612 ::
 613
 614       >>> p = Point(x=11, y=22)
 615       >>> p._replace(x=33)
 616       Point(x=33, y=22)
 617
 618       >>> for partnum, record in inventory.items():
 619       ...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
 620
 621 .. attribute:: somenamedtuple._fields
 622
 623    Tuple of strings listing the field names.  Useful for introspection
 624    and for creating new named tuple types from existing named tuples.
 625
 626 .. doctest::
 627
 628       >>> p._fields            # view the field names
 629       ('x', 'y')
 630
 631       >>> Color = namedtuple('Color', 'red green blue')
 632       >>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
 633       >>> Pixel(11, 22, 128, 255, 0)
 634       Pixel(x=11, y=22, red=128, green=255, blue=0)
 635
 636 To retrieve a field whose name is stored in a string, use the :func:`getattr`
 637 function:
 638
 639     >>> getattr(p, 'x')
 640     11
 641
 642 To convert a dictionary to a named tuple, use the double-star-operator [#]_:
 643
 644    >>> d = {'x': 11, 'y': 22}
 645    >>> Point(**d)
 646    Point(x=11, y=22)
 647
 648 Since a named tuple is a regular Python class, it is easy to add or change
 649 functionality with a subclass.  Here is how to add a calculated field and
 650 a fixed-width print format:
 651
 652     >>> class Point(namedtuple('Point', 'x y')):
 653     ...     __slots__ = ()
 654     ...     @property
 655     ...     def hypot(self):
 656     ...         return (self.x ** 2 + self.y ** 2) ** 0.5
 657     ...     def __str__(self):
 658     ...         return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)
 659
 660     >>> for p in Point(3, 4), Point(14, 5/7.):
 661     ...     print p
 662     Point: x= 3.000  y= 4.000  hypot= 5.000
 663     Point: x=14.000  y= 0.714  hypot=14.018
 664
 665 The subclass shown above sets ``__slots__`` to an empty tuple.  This keeps
 666 keep memory requirements low by preventing the creation of instance dictionaries.
 667
 668 Subclassing is not useful for adding new, stored fields.  Instead, simply
 669 create a new named tuple type from the :attr:`_fields` attribute:
 670
 671     >>> Point3D = namedtuple('Point3D', Point._fields + ('z',))
 672
 673 Default values can be implemented by using :meth:`_replace` to
 674 customize a prototype instance:
 675
 676     >>> Account = namedtuple('Account', 'owner balance transaction_count')
 677     >>> default_account = Account('<owner name>', 0.0, 0)
 678     >>> johns_account = default_account._replace(owner='John')
 679
 680 Enumerated constants can be implemented with named tuples, but it is simpler
 681 and more efficient to use a simple class declaration:
 682
 683     >>> Status = namedtuple('Status', 'open pending closed')._make(range(3))
 684     >>> Status.open, Status.pending, Status.closed
 685     (0, 1, 2)
 686     >>> class Status:
 687     ...     open, pending, closed = range(3)
 688
 689 .. rubric:: Footnotes
 690
 691 .. [#] For information on the double-star-operator see
 692    :ref:`tut-unpacking-arguments` and :ref:`calls`.