Lib/collections.py

   1 __all__ = ['deque', 'defaultdict', 'NamedTuple']
   2
   3 from _collections import deque, defaultdict
   4 from operator import itemgetter as _itemgetter
   5 import sys as _sys
   6
   7 def NamedTuple(typename, s, verbose=False):
   8     """Returns a new subclass of tuple with named fields.
   9
  10     >>> Point = NamedTuple('Point', 'x y')
  11     >>> Point.__doc__                   # docstring for the new class
  12     'Point(x, y)'
  13     >>> p = Point(11, y=22)             # instantiate with positional args or keywords
  14     >>> p[0] + p[1]                     # works just like the tuple (11, 22)
  15     33
  16     >>> x, y = p                        # unpacks just like a tuple
  17     >>> x, y
  18     (11, 22)
  19     >>> p.x + p.y                       # fields also accessable by name
  20     33
  21     >>> p                               # readable __repr__ with name=value style
  22     Point(x=11, y=22)
  23     >>> p.__replace__('x', 100)         # __replace__() is like str.replace() but targets a named field
  24     Point(x=100, y=22)
  25     >>> d = dict(zip(p.__fields__, p))  # use __fields__ to make a dictionary
  26     >>> d['x']
  27     11
  28
  29     """
  30
  31     field_names = tuple(s.replace(',', ' ').split())    # names separated by spaces and/or commas
  32     if not ''.join((typename,) + field_names).replace('_', '').isalnum():
  33         raise ValueError('Type names and field names can only contain alphanumeric characters and underscores')
  34     argtxt = repr(field_names).replace("'", "")[1:-1]   # tuple repr without parens or quotes
  35     reprtxt = ', '.join('%s=%%r' % name for name in field_names)
  36     template = '''class %(typename)s(tuple):
  37         '%(typename)s(%(argtxt)s)'
  38         __slots__ = ()
  39         __fields__ = %(field_names)r
  40         def __new__(cls, %(argtxt)s):
  41             return tuple.__new__(cls, (%(argtxt)s))
  42         def __repr__(self):
  43             return '%(typename)s(%(reprtxt)s)' %% self
  44         def __replace__(self, field, value):
  45             'Return a new %(typename)s object replacing one field with a new value'
  46             return %(typename)s(**dict(zip(%(field_names)r, self) + [(field, value)]))  \n''' % locals()
  47     for i, name in enumerate(field_names):
  48         template += '        %s = property(itemgetter(%d))\n' % (name, i)
  49     if verbose:
  50         print template
  51     m = dict(itemgetter=_itemgetter)
  52     exec template in m
  53     result = m[typename]
  54     if hasattr(_sys, '_getframe'):
  55         result.__module__ = _sys._getframe(1).f_globals['__name__']
  56     return result
  57
  58
  59
  60
  61
  62
  63 if __name__ == '__main__':
  64     # verify that instances can be pickled
  65     from cPickle import loads, dumps
  66     Point = NamedTuple('Point', 'x, y', True)
  67     p = Point(x=10, y=20)
  68     assert p == loads(dumps(p))
  69
  70     import doctest
  71     TestResults = NamedTuple('TestResults', 'failed attempted')
  72     print TestResults(*doctest.testmod())