|
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:`MutableSequnce` :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, fieldnames, [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 fieldnames) and a helpful :meth:`__repr__` |
|
496 method which lists the tuple contents in a ``name=value`` format. |
|
497 |
|
498 The *fieldnames* are a single string with each fieldname separated by whitespace |
|
499 and/or commas, for example ``'x y'`` or ``'x, y'``. Alternatively, *fieldnames* |
|
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`. |