8.3. `collections` — 容器数据类型 ¶

此模块实现专用容器数据类型，提供备选为 Python 一般目的内置容器 dict , list , set ，和 tuple .

`namedtuple()`	采用命名字段创建 tuple 子类的工厂函数
`deque`	两端都能快速追加和弹出的像 list 容器
`ChainMap`	用于创建多映射的单个视图的像 dict 类
`Counter`	用于计数可哈希对象的 dict 子类
`OrderedDict`	能记住条目添加次序的 dict 子类
`defaultdict`	调用工厂函数以提供缺少值的 dict 子类
`UserDict`	围绕字典对象的包裹器为更易于 dict 子类化
`UserList`	围绕列表对象的包裹器，为更容易 list 子类化
`UserString`	围绕字符串对象的包裹器为更易于字符串子类化

3.3 版改变：移动集合抽象基类到 collections.abc 模块。为向后兼容，在此模块中他们仍继续可见。

8.3.1. `ChainMap` 对象 ¶

3.3 版新增。

A ChainMap 类是为快速链接很多映射而提供的，因此可以将它们视为单个单元。它通常快得多，比创建新字典并运行多个 update() 调用。

此类可以用于模拟嵌套作用域，且在模板中很有用。

class collections. ChainMap ( *maps ) ¶

maps ¶

new_child ( m=None ) ¶

parents ¶

另请参阅

The MultiContext 类 in the Enthought CodeTools 包 has options to support writing to any mapping in the chain.
Django 的 Context 类 for templating is a read-only chain of mappings. It also features pushing and popping of contexts similar to the new_child() 方法和 parents() 特性。
The 嵌套上下文配方 has options to control whether writes and other mutations apply only to the first mapping or to any mapping in the chain.
A greatly simplified read-only version of Chainmap .

8.3.1.1. `ChainMap` 范例和配方 ¶

This section shows various approaches to working with chained maps.

Example of simulating Python’s internal lookup chain:

import builtins
pylookup = ChainMap(locals(), globals(), vars(builtins))

Example of letting user specified command-line arguments take precedence over environment variables which in turn take precedence over default values:

import os, argparse
defaults = {'color': 'red', 'user': 'guest'}
parser = argparse.ArgumentParser()
parser.add_argument('-u', '--user')
parser.add_argument('-c', '--color')
namespace = parser.parse_args()
command_line_args = {k:v for k, v in vars(namespace).items() if v}
combined = ChainMap(command_line_args, os.environ, defaults)
print(combined['color'])
print(combined['user'])

Example patterns for using the ChainMap class to simulate nested contexts:

c = ChainMap()        # Create root context
d = c.new_child()     # Create nested child context
e = c.new_child()     # Child of c, independent from d
e.maps[0]             # Current context dictionary -- like Python's locals()
e.maps[-1]            # Root context -- like Python's globals()
e.parents             # Enclosing context chain -- like Python's nonlocals
d['x']                # Get first key in the chain of contexts
d['x'] = 1            # Set value in current context
del d['x']            # Delete from current context
list(d)               # All nested values
k in d                # Check all nested values
len(d)                # Number of nested values
d.items()             # All nested items
dict(d)               # Flatten into a regular dictionary

The ChainMap class only makes updates (writes and deletions) to the first mapping in the chain while lookups will search the full chain. However, if deep writes and deletions are desired, it is easy to make a subclass that updates keys found deeper in the chain:

class DeepChainMap(ChainMap):
    'Variant of ChainMap that allows direct updates to inner scopes'
    def __setitem__(self, key, value):
        for mapping in self.maps:
            if key in mapping:
                mapping[key] = value
                return
        self.maps[0][key] = value
    def __delitem__(self, key):
        for mapping in self.maps:
            if key in mapping:
                del mapping[key]
                return
        raise KeyError(key)
>>> d = DeepChainMap({'zebra': 'black'}, {'elephant': 'blue'}, {'lion': 'yellow'})
>>> d['lion'] = 'orange'         # update an existing key two levels down
>>> d['snake'] = 'red'           # new keys get added to the topmost dict
>>> del d['elephant']            # remove an existing key one level down
DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})

8.3.2. `Counter` 对象 ¶

计数器工具的提供以支持方便、快速计数。例如：

>>> # Tally occurrences of words in a list
>>> cnt = Counter()
>>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
...     cnt[word] += 1
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1})
>>> # Find the ten most common words in Hamlet
>>> import re
>>> words = re.findall(r'\w+', open('hamlet.txt').read().lower())
>>> Counter(words).most_common(10)
[('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),
 ('you', 554),  ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]

class collections. Counter ( [ iterable-or-mapping ] ) ¶

elements ( ) ¶

most_common ( [ n ] ) ¶

subtract ( [ iterable-or-mapping ] ) ¶

The usual dictionary methods are available for Counter objects except for two which work differently for counters.

fromkeys ( iterable ) ¶

update ( [ iterable-or-mapping ] ) ¶

Common patterns for working with Counter 对象：

sum(c.values())                 # total of all counts
c.clear()                       # reset all counts
list(c)                         # list unique elements
set(c)                          # convert to a set
dict(c)                         # convert to a regular dictionary
c.items()                       # convert to a list of (elem, cnt) pairs
Counter(dict(list_of_pairs))    # convert from a list of (elem, cnt) pairs
c.most_common()[:-n-1:-1]       # n least common elements
+c                              # remove zero and negative counts

Several mathematical operations are provided for combining Counter objects to produce multisets (counters that have counts greater than zero). Addition and subtraction combine counters by adding or subtracting the counts of corresponding elements. Intersection and union return the minimum and maximum of corresponding counts. Each operation can accept inputs with signed counts, but the output will exclude results with counts of zero or less.

>>> c = Counter(a=3, b=1)
>>> d = Counter(a=1, b=2)
>>> c + d                       # add two counters together:  c[x] + d[x]
Counter({'a': 4, 'b': 3})
>>> c - d                       # subtract (keeping only positive counts)
Counter({'a': 2})
>>> c & d                       # intersection:  min(c[x], d[x]) 
Counter({'a': 1, 'b': 1})
>>> c | d                       # union:  max(c[x], d[x])
Counter({'a': 3, 'b': 2})

Unary addition and subtraction are shortcuts for adding an empty counter or subtracting from an empty counter.

>>> c = Counter(a=2, b=-4)
>>> +c
Counter({'a': 2})
>>> -c
Counter({'b': 4})

3.3 版新增： Added support for unary plus, unary minus, and in-place multiset operations.

注意

Counters were primarily designed to work with positive integers to represent running counts; however, care was taken to not unnecessarily preclude use cases needing other types or negative values. To help with those use cases, this section documents the minimum range and type restrictions.

The Counter class itself is a dictionary subclass with no restrictions on its keys and values. The values are intended to be numbers representing counts, but you could store anything in the value field.
The most_common() method requires only that the values be orderable.
For in-place operations such as c[key] += 1 , the value type need only support addition and subtraction. So fractions, floats, and decimals would work and negative values are supported. The same is also true for update() and subtract() which allow negative and zero values for both inputs and outputs.
The multiset methods are designed only for use cases with positive values. The inputs may be negative or zero, but only outputs with positive values are created. There are no type restrictions, but the value type needs to support addition, subtraction, and comparison.
The elements() method requires integer counts. It ignores zero and negative counts.

另请参阅

Bag class in Smalltalk.
维基百科条目对于 Multisets .
C++ multisets tutorial with examples.
For mathematical operations on multisets and their use cases, see Knuth, Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise 19 .
To enumerate all distinct multisets of a given size over a given set of elements, see itertools.combinations_with_replacement() :

map(Counter, combinations_with_replacement(‘ABC’, 2)) –> AA AB AC BB BC CC

8.3.3. `deque` 对象 ¶

class collections. deque ( [ iterable [ , maxlen ] ] ) ¶

In addition to the above, deques support iteration, pickling, len(d) , reversed(d) , copy.copy(d) , copy.deepcopy(d) , membership testing with the in operator, and subscript references such as d[-1] . Indexed access is O(1) at both ends but slows to O(n) in the middle. For fast random access, use lists instead.

Starting in version 3.5, deques support __add__() , __mul__() ，和 __imul__() .

范例：

>>> from collections import deque
>>> d = deque('ghi')                 # make a new deque with three items
>>> for elem in d:                   # iterate over the deque's elements
...     print(elem.upper())
G
H
I
>>> d.append('j')                    # add a new entry to the right side
>>> d.appendleft('f')                # add a new entry to the left side
>>> d                                # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])
>>> d.pop()                          # return and remove the rightmost item
'j'
>>> d.popleft()                      # return and remove the leftmost item
'f'
>>> list(d)                          # list the contents of the deque
['g', 'h', 'i']
>>> d[0]                             # peek at leftmost item
'g'
>>> d[-1]                            # peek at rightmost item
'i'
>>> list(reversed(d))                # list the contents of a deque in reverse
['i', 'h', 'g']
>>> 'h' in d                         # search the deque
True
>>> d.extend('jkl')                  # add multiple elements at once
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> d.rotate(1)                      # right rotation
>>> d
deque(['l', 'g', 'h', 'i', 'j', 'k'])
>>> d.rotate(-1)                     # left rotation
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> deque(reversed(d))               # make a new deque in reverse order
deque(['l', 'k', 'j', 'i', 'h', 'g'])
>>> d.clear()                        # empty the deque
>>> d.pop()                          # cannot pop from an empty deque
Traceback (most recent call last):
    File "<pyshell#6>", line 1, in -toplevel-
        d.pop()
IndexError: pop from an empty deque
>>> d.extendleft('abc')              # extendleft() reverses the input order
>>> d
deque(['c', 'b', 'a'])

8.3.3.1. `deque` 配方 ¶

This section shows various approaches to working with deques.

Bounded length deques provide functionality similar to the tail filter in Unix:

def tail(filename, n=10):
    'Return the last n lines of a file'
    with open(filename) as f:
        return deque(f, n)

Another approach to using deques is to maintain a sequence of recently added elements by appending to the right and popping to the left:

def moving_average(iterable, n=3):
    # moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0
    # http://en.wikipedia.org/wiki/Moving_average
    it = iter(iterable)
    d = deque(itertools.islice(it, n-1))
    d.appendleft(0)
    s = sum(d)
    for elem in it:
        s += elem - d.popleft()
        d.append(elem)
        yield s / n

The rotate() method provides a way to implement deque slicing and deletion. For example, a pure Python implementation of del d[n] relies on the rotate() method to position elements to be popped:

def delete_nth(d, n):
    d.rotate(-n)
    d.popleft()
    d.rotate(n)

要实现 deque slicing, use a similar approach applying rotate() to bring a target element to the left side of the deque. Remove old entries with popleft() , add new entries with extend() , and then reverse the rotation. With minor variations on that approach, it is easy to implement Forth style stack manipulations such as dup , drop , swap , over , pick , rot ，和 roll .

8.3.4. `defaultdict` 对象 ¶

class collections. defaultdict ( [ default_factory [ , ... ] ] ) ¶

8.3.4.1. `defaultdict` 范例 ¶

使用 list 作为 default_factory , it is easy to group a sequence of key-value pairs into a dictionary of lists:

>>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
>>> d = defaultdict(list)
>>> for k, v in s:
...     d[k].append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

When each key is encountered for the first time, it is not already in the mapping; so an entry is automatically created using the default_factory function which returns an empty list 。 list.append() operation then attaches the value to the new list. When keys are encountered again, the look-up proceeds normally (returning the list for that key) and the list.append() operation adds another value to the list. This technique is simpler and faster than an equivalent technique using dict.setdefault() :

>>> d = {}
>>> for k, v in s:
...     d.setdefault(k, []).append(v)
...
>>> sorted(d.items())
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]

设置 default_factory to int makes the defaultdict useful for counting (like a bag or multiset in other languages):

>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
...     d[k] += 1
...
>>> sorted(d.items())
[('i', 4), ('m', 1), ('p', 2), ('s', 4)]

When a letter is first encountered, it is missing from the mapping, so the default_factory 函数调用 int() to supply a default count of zero. The increment operation then builds up the count for each letter.

函数 int() which always returns zero is just a special case of constant functions. A faster and more flexible way to create constant functions is to use a lambda function which can supply any constant value (not just zero):

>>> def constant_factory(value):
...     return lambda: value
>>> d = defaultdict(constant_factory('<missing>'))
>>> d.update(name='John', action='ran')
>>> '%(name)s %(action)s to %(object)s' % d
'John ran to <missing>'

设置 default_factory to set makes the defaultdict useful for building a dictionary of sets:

>>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
>>> d = defaultdict(set)
>>> for k, v in s:
...     d[k].add(v)
...
>>> sorted(d.items())
[('blue', {2, 4}), ('red', {1, 3})]

8.3.5. `namedtuple()` 用于带命名字段的元组的工厂函数 ¶

命名元组将含义赋值给元组中的每个位置，且允许更可读、自文档化代码。它们可以用于任何使用常规元组的地方，且通过名称而不是位置索引添加访问字段的能力。

collections. namedtuple ( typename , field_names , verbose=False , rename=False ) ¶

>>> # Basic example
>>> Point = namedtuple('Point', ['x', 'y'])
>>> p = Point(11, y=22)     # instantiate with positional or keyword arguments
>>> p[0] + p[1]             # indexable like the plain tuple (11, 22)
33
>>> x, y = p                # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y               # fields also accessible by name
33
>>> p                       # readable __repr__ with a name=value style
Point(x=11, y=22)

命名元组尤其有用，把字段名赋值给结果元组返回通过 csv or sqlite3 模块：

EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')
import csv
for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
    print(emp.name, emp.title)
import sqlite3
conn = sqlite3.connect('/companydata')
cursor = conn.cursor()
cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
for emp in map(EmployeeRecord._make, cursor.fetchall()):
    print(emp.name, emp.title)

从元组继承的方法除外，命名元组还支持 3 方法和 2 属性。为防止与字段名冲突，方法和属性名以下划线开头。

classmethod somenamedtuple. _make ( iterable ) ¶

somenamedtuple. _asdict ( ) ¶

8.3. `collections` — 容器数据类型 ¶

8.3.1. `ChainMap` 对象 ¶

8.3.1.1. `ChainMap` 范例和配方 ¶

8.3.2. `Counter` 对象 ¶

8.3.3. `deque` 对象 ¶

8.3.3.1. `deque` 配方 ¶

8.3.4. `defaultdict` 对象 ¶

8.3.4.1. `defaultdict` 范例 ¶

8.3.5. `namedtuple()` 用于带命名字段的元组的工厂函数 ¶

8.3.6. `OrderedDict` 对象 ¶

8.3.6.1. `OrderedDict` 范例和配方 ¶

8.3.7. `UserDict` 对象 ¶

8.3.8. `UserList` 对象 ¶

8.3.9. `UserString` 对象 ¶

内容表

上一话题

下一话题

本页

8.3. collections — 容器数据类型 ¶

8.3.1. ChainMap 对象 ¶

8.3.1.1. ChainMap 范例和配方 ¶

8.3.2. Counter 对象 ¶

8.3.3. deque 对象 ¶

8.3.3.1. deque 配方 ¶

8.3.4. defaultdict 对象 ¶

8.3.4.1. defaultdict 范例 ¶

8.3.5. namedtuple() 用于带命名字段的元组的工厂函数 ¶

8.3.6. OrderedDict 对象 ¶

8.3.6.1. OrderedDict 范例和配方 ¶

8.3.7. UserDict 对象 ¶

8.3.8. UserList 对象 ¶

8.3.9. UserString 对象 ¶

内容表

上一话题

下一话题

本页

8.3. `collections` — 容器数据类型 ¶

8.3.1. `ChainMap` 对象 ¶

8.3.1.1. `ChainMap` 范例和配方 ¶

8.3.2. `Counter` 对象 ¶

8.3.3. `deque` 对象 ¶

8.3.3.1. `deque` 配方 ¶

8.3.4. `defaultdict` 对象 ¶

8.3.4.1. `defaultdict` 范例 ¶

8.3.5. `namedtuple()` 用于带命名字段的元组的工厂函数 ¶

8.3.6. `OrderedDict` 对象 ¶

8.3.6.1. `OrderedDict` 范例和配方 ¶

8.3.7. `UserDict` 对象 ¶

8.3.8. `UserList` 对象 ¶

8.3.9. `UserString` 对象 ¶