diff options
Diffstat (limited to 'Doc/library/collections.rst')
| -rw-r--r-- | Doc/library/collections.rst | 48 |
1 files changed, 34 insertions, 14 deletions
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index ba3ce31..0b856fe 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -10,7 +10,7 @@ This module implements high-performance container datatypes. Currently, there are two datatypes, :class:`deque` and :class:`defaultdict`, and -one datatype factory function, :func:`named_tuple`. Python already +one datatype factory function, :func:`namedtuple`. Python already includes built-in containers, :class:`dict`, :class:`list`, :class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb` module has a :meth:`bsddb.btopen` method that can be used to create in-memory @@ -383,14 +383,14 @@ Setting the :attr:`default_factory` to :class:`set` makes the .. _named-tuple-factory: -:func:`named_tuple` Factory Function for Tuples with Named Fields +:func:`namedtuple` Factory Function for Tuples with Named Fields ----------------------------------------------------------------- Named tuples assign meaning to each position in a tuple and allow for more readable, self-documenting code. They can be used wherever regular tuples are used, and they add the ability to access fields by name instead of position index. -.. function:: named_tuple(typename, fieldnames, [verbose]) +.. function:: namedtuple(typename, fieldnames, [verbose]) Returns a new tuple subclass named *typename*. The new subclass is used to create tuple-like objects that have fields accessable by attribute lookup as @@ -415,7 +415,7 @@ they add the ability to access fields by name instead of position index. Example:: - >>> Point = named_tuple('Point', 'x y', verbose=True) + >>> Point = namedtuple('Point', 'x y', verbose=True) class Point(tuple): 'Point(x, y)' __slots__ = () @@ -428,8 +428,8 @@ Example:: 'Return a new dict mapping field names to their values' return dict(zip(('x', 'y'), self)) def __replace__(self, field, value): - 'Return a new Point object replacing one field with a new value' - return Point(**dict(zip(('x', 'y'), self) + [(field, value)])) + 'Return a new Point object replacing specified fields with new values' + return Point(**dict(zip(('x', 'y'), self) + kwds.items())) x = property(itemgetter(0)) y = property(itemgetter(1)) @@ -447,7 +447,7 @@ Example:: Named tuples are especially useful for assigning field names to result tuples returned by the :mod:`csv` or :mod:`sqlite3` modules:: - EmployeeRecord = named_tuple('EmployeeRecord', 'name, age, title, department, paygrade') + EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade') from itertools import starmap import csv @@ -486,18 +486,18 @@ two additonal methods and a read-only attribute. >>> p.__asdict__() {'x': 11, 'y': 22} -.. method:: somenamedtuple.__replace__(field, value) +.. method:: somenamedtuple.__replace__(kwargs) - Return a new instance of the named tuple replacing the named *field* with a new *value*: + Return a new instance of the named tuple replacing specified fields with new values: :: >>> p = Point(x=11, y=22) - >>> p.__replace__('x', 33) + >>> p.__replace__(x=33) Point(x=33, y=22) - >>> for recordnum, record in inventory: - ... inventory[recordnum] = record.replace('total', record.price * record.quantity) + >>> for partnum, record in inventory.items(): + ... inventory[partnum] = record.__replace__(price=newprices[partnum], updated=time.now()) .. attribute:: somenamedtuple.__fields__ @@ -509,11 +509,31 @@ two additonal methods and a read-only attribute. >>> p.__fields__ # view the field names ('x', 'y') - >>> Color = named_tuple('Color', 'red green blue') - >>> Pixel = named_tuple('Pixel', Point.__fields__ + Color.__fields__) + >>> Color = namedtuple('Color', 'red green blue') + >>> Pixel = namedtuple('Pixel', Point.__fields__ + Color.__fields__) >>> Pixel(11, 22, 128, 255, 0) Pixel(x=11, y=22, red=128, green=255, blue=0)' +Since a named tuple is a regular Python class, it is easy to add or change +functionality. For example, the display format can be changed by overriding +the :meth:`__repr__` method: + +:: + + >>> Point = namedtuple('Point', 'x y') + >>> Point.__repr__ = lambda self: 'Point(%.3f, %.3f)' % self + >>> Point(x=10, y=20) + Point(10.000, 20.000) + +Default values can be implemented by starting with a prototype instance +and customizing it with :meth:`__replace__`: + +:: + + >>> Account = namedtuple('Account', 'owner balance transaction_count') + >>> model_account = Account('<owner name>', 0.0, 0) + >>> johns_account = model_account.__replace__(owner='John') + .. rubric:: Footnotes .. [#] For information on the star-operator see |