collections — 容器数据类型

源代码： Lib/collections/__init__.py

---

此模块实现了专门的容器数据类型，为 Python 的通用内置容器 dict、list、set 和 tuple 提供了替代方案。

namedtuple()	创建带有命名字段的元组子类的工厂函数
deque	类似列表的容器，可在两端快速追加和弹出
ChainMap	类似字典的类，用于创建多个映射的单一视图
Counter	用于对可哈希对象计数的字典子类
OrderedDict	记住条目添加顺序的字典子类
defaultdict	调用工厂函数以提供缺失值的字典子类
UserDict	字典对象的包装器，便于子类化字典
UserList	列表对象的包装器，便于子类化列表
UserString	字符串对象的包装器，便于子类化字符串

ChainMap 对象

在 3.3 版本加入。

提供 ChainMap 类，用于快速将多个映射链接在一起，以便将它们视为一个单元。它通常比创建一个新字典并多次运行 update() 调用要快得多。

该类可用于模拟嵌套作用域，在模板化中非常有用。

class collections.ChainMap(*maps)

ChainMap 将多个字典或其他映射组合在一起，创建一个单一、可更新的视图。如果未指定 maps，则提供一个空字典，以确保新的链中始终至少有一个映射。

底层的映射存储在一个列表中。该列表是公开的，可以使用 maps 属性进行访问或更新。没有其他状态。

查找会依次搜索底层映射，直到找到一个键。相比之下，写入、更新和删除操作只作用于第一个映射。

ChainMap 通过引用包含底层映射。因此，如果其中一个底层映射被更新，这些更改将反映在 ChainMap 中。

支持所有常规的字典方法。此外，还有一个 maps 属性，一个用于创建新子上下文的方法，以及一个用于访问除第一个映射之外所有映射的属性。

maps

一个用户可更新的映射列表。该列表从第一个搜索到最后一个搜索进行排序。它是唯一存储的状态，并且可以被修改以更改搜索的映射。该列表应始终包含至少一个映射。

new_child(m=None, **kwargs)

返回一个新的 ChainMap，其中包含一个新的映射，后面跟着当前实例中的所有映射。如果指定了 m，它将成为映射列表最前面的新映射；如果未指定，则使用一个空字典，因此调用 d.new_child() 等同于：ChainMap({}, *d.maps)。如果指定了任何关键字参数，它们会更新传入的映射或新的空字典。此方法用于创建可以更新而不会改变任何父映射中值的子上下文。

在 3.4 版更改: 增加了可选的 m 形参。

在 3.10 版更改: 添加了对关键字参数的支持。

parents

返回一个新的 ChainMap 的属性，该 ChainMap 包含当前实例中除第一个映射外的所有映射。这对于在搜索中跳过第一个映射很有用。用例类似于嵌套作用域中使用的 nonlocal 关键字的用例。用例也与内置的 super() 函数相似。对 d.parents 的引用等价于：ChainMap(*d.maps[1:])。

注意，ChainMap 的迭代顺序是通过从后向前扫描映射来确定的。

>>> baseline = {'music': 'bach', 'art': 'rembrandt'}
>>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}
>>> list(ChainMap(adjustments, baseline))
['music', 'art', 'opera']

这与从最后一个映射开始的一系列 dict.update() 调用给出的顺序相同。

>>> combined = baseline.copy()
>>> combined.update(adjustments)
>>> list(combined)
['music', 'art', 'opera']

在 3.9 版更改: 添加了对 | 和 |= 运算符的支持，详见 PEP 584。

参见

• Enthought CodeTools 包中的 MultiContext 类 提供了支持写入链中任何映射的选项。

• Django 用于模板化的 Context 类是一个只读的映射链。它还具有类似于 new_child() 方法和 parents 属性的上下文推入和弹出功能。

• Nested Contexts recipe 提供了选项来控制写入和其他修改是仅应用于第一个映射还是链中的任何映射。

• Chainmap 的一个极大简化的只读版本。

ChainMap 示例和技巧

本节展示了使用链式映射的各种方法。

模拟 Python 内部查找链的示例

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

让用户指定的命令行参数优先于环境变量，环境变量又优先于默认值的示例

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 is not None}

combined = ChainMap(command_line_args, os.environ, defaults)
print(combined['color'])
print(combined['user'])

使用 ChainMap 类模拟嵌套上下文的示例模式

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'] = 1            # Set value in current context
d['x']                # Get first key in the chain of contexts
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

ChainMap 类只对链中的第一个映射进行更新（写入和删除），而查找将搜索整个链。但是，如果需要深度写入和删除，可以很容易地创建一个子类来更新在链中更深处找到的键。

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
>>> d                            # display result
DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})

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])

Counter 是一个 dict 子类，用于对可哈希对象进行计数。它是一个集合，其中元素作为字典键存储，它们的计数作为字典值存储。计数可以是任何整数值，包括零或负计数。Counter 类类似于其他语言中的 bag 或 multiset。

元素可以从一个 iterable 中计数，或者从另一个 mapping（或 counter）初始化

>>> c = Counter()                           # a new, empty counter
>>> c = Counter('gallahad')                 # a new counter from an iterable
>>> c = Counter({'red': 4, 'blue': 2})      # a new counter from a mapping
>>> c = Counter(cats=4, dogs=8)             # a new counter from keyword args

Counter 对象具有字典接口，但对于不存在的项，它们会返回零计数，而不是引发 KeyError。

>>> c = Counter(['eggs', 'ham'])
>>> c['bacon']                              # count of a missing element is zero
0

将计数设置为零不会从计数器中移除元素。使用 del 将其完全移除。

>>> c['sausage'] = 0                        # counter entry with a zero count
>>> del c['sausage']                        # del actually removes the entry

在 3.1 版本加入。

在 3.7 版更改: 作为 dict 的子类，Counter 继承了记住插入顺序的能力。对 Counter 对象的数学运算也会保留顺序。结果根据元素在左操作数中首次出现的顺序，然后是右操作数中出现的顺序进行排序。

除了所有字典可用的方法外，Counter 对象还支持其他方法：

elements()

返回一个迭代器，其中每个元素重复的次数等于其计数。元素按首次遇到的顺序返回。如果一个元素的计数小于一，elements() 将忽略它。

>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> sorted(c.elements())
['a', 'a', 'a', 'a', 'b', 'b']

most_common([n])

返回一个包含 n 个最常见元素及其计数的列表，从最常见到最不常见。如果省略 n 或为 None，most_common() 将返回计数器中的所有元素。计数相等的元素按首次遇到的顺序排序。

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]

subtract([iterable-or-mapping])

从一个 iterable 或另一个 mapping（或 counter）中减去元素。类似于 dict.update()，但它是减去计数而不是替换它们。输入和输出都可以是零或负数。

>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> d = Counter(a=1, b=2, c=3, d=4)
>>> c.subtract(d)
>>> c
Counter({'a': 3, 'b': 0, 'c': -3, 'd': -6})

在 3.2 版本加入。

total()

计算计数的总和。

>>> c = Counter(a=10, b=5, c=0)
>>> c.total()
15

在 3.10 版本加入。

通常的字典方法可用于 Counter 对象，但有两个方法对计数器的工作方式不同。

fromkeys(iterable)

这个类方法没有为 Counter 对象实现。

update([iterable-or-mapping])

从 iterable 中统计元素，或者从另一个 mapping（或 counter）中增加。类似于 dict.update()，但它是增加计数而不是替换它们。此外，iterable 应为元素序列，而不是 (key, value) 对的序列。

计数器支持丰富的比较运算符，用于相等性、子集和超集关系：==、!=、<、<=、>、>=。所有这些测试都将缺失的元素视为计数为零，因此 Counter(a=1) == Counter(a=1, b=0) 返回 true。

在 3.10 版更改: 增加了富比较运算。

在 3.10 版更改: 在相等性测试中，缺失的元素被视为计数为零。以前，Counter(a=3) 和 Counter(a=3, b=0) 被认为是不同的。

使用 Counter 对象的常见模式

c.total()                       # 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()                       # access the (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

提供了几种数学运算来组合 Counter 对象，以产生多重集（计数大于零的计数器）。加法和减法通过加或减相应元素的计数来组合计数器。交集和并集返回相应计数的最小值和最大值。相等性和包含性比较相应计数。每个操作都可以接受带符号计数的输入，但输出将排除计数为零或更少的结果。

>>> 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})
>>> c == d                      # equality:  c[x] == d[x]
False
>>> c <= d                      # inclusion:  c[x] <= d[x]
False

一元加法和减法是与空计数器相加或从空计数器中减去的快捷方式。

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

3.3 新版功能: 添加了对一元加、一元减和原地多重集操作的支持。

备注

计数器主要是为使用正整数表示运行计数而设计的；然而，我们注意不要不必要地排除需要其他类型或负值的用例。为了帮助这些用例，本节记录了最小范围和类型限制。

• Counter 类本身是字典的子类，对其键和值没有限制。值旨在表示计数的数字，但你可以在值字段中存储任何东西。

• most_common() 方法仅要求值是可排序的。

• 对于原地操作，如 c[key] += 1，值类型只需要支持加法和减法。因此，分数、浮点数和十进制数都可以工作，并且支持负值。这同样适用于 update() 和 subtract()，它们都允许输入和输出为负值和零值。

• 多重集方法仅设计用于具有正值的用例。输入可以是负数或零，但只创建具有正值的输出。没有类型限制，但值类型需要支持加法、减法和比较。

• elements() 方法需要整数计数。它会忽略零和负计数。

参见

• Smalltalk 中的 Bag 类。

• 维基百科关于 Multisets 的条目。

• C++ multisets 教程及示例。

• 有关多重集的数学运算及其用例，请参见 Knuth, Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise 19。

• 要枚举给定元素集上给定大小的所有不同多重集，请参阅 itertools.combinations_with_replacement()。

  map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC
  

deque 对象

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

返回一个新的双端队列对象，该对象使用来自 iterable 的数据从左到右（使用 append()）初始化。如果未指定 iterable，则新双端队列为空。

双端队列是栈和队列的泛化（名称发音为“deck”，是“double-ended queue”的缩写）。双端队列支持线程安全、内存高效地从双端队列的任一端追加和弹出，两端的操作都具有大致相同的 O(1) 性能。

虽然 list 对象支持类似的操作，但它们是为快速的固定长度操作而优化的，对于 pop(0) 和 insert(0, v) 操作，会产生 O(n) 的内存移动成本，这些操作会改变底层数据表示的大小和位置。

如果未指定 maxlen 或为 None，双端队列可以增长到任意长度。否则，双端队列受限于指定的最大长度。一旦有界长度的双端队列已满，当添加新项时，相应数量的项会从另一端丢弃。有界长度的双端队列提供了与 Unix 中 tail 过滤器类似的功能。它们还可用于跟踪事务和其他只关心最新活动的数据池。

双端队列对象支持以下方法：

append(x)

将 x 添加到双端队列的右侧。

appendleft(x)

将 x 添加到双端队列的左侧。

clear()

从双端队列中移除所有元素，使其长度为 0。

copy()

创建双端队列的浅拷贝。

在 3.5 版本加入。

count(x)

计算双端队列中等于 x 的元素数量。

在 3.2 版本加入。

extend(iterable)

通过从可迭代参数中追加元素来扩展双端队列的右侧。

extendleft(iterable)

通过从 iterable 中追加元素来扩展双端队列的左侧。注意，一系列的左侧追加会导致可迭代参数中元素的顺序反转。

index(x[, start[, stop]])

返回 x 在双端队列中的位置（在索引 start 之后，索引 stop 之前）。返回第一个匹配项，如果未找到则引发 ValueError。

在 3.5 版本加入。

insert(i, x)

在位置 i 处将 x 插入到双端队列中。

如果插入操作会导致有界双端队列超出 maxlen，则会引发 IndexError。

在 3.5 版本加入。

pop()

从双端队列的右侧移除并返回一个元素。如果没有元素存在，则引发 IndexError。

popleft()

从双端队列的左侧移除并返回一个元素。如果没有元素存在，则引发 IndexError。

remove(value)

移除 value 的首次出现。如果未找到，则引发 ValueError。

reverse()

原地反转双端队列的元素，然后返回 None。

在 3.2 版本加入。

rotate(n=1)

将双端队列向右旋转 n 步。如果 n 是负数，则向左旋转。

当双端队列不为空时，向右旋转一步相当于 d.appendleft(d.pop())，向左旋转一步相当于 d.append(d.popleft())。

双端队列对象还提供一个只读属性：

maxlen

双端队列的最大大小，如果无界则为 None。

在 3.1 版本加入。

除了上述功能外，双端队列还支持迭代、序列化、len(d)、reversed(d)、copy.copy(d)、copy.deepcopy(d)、使用 in 运算符进行成员测试，以及通过下标引用（如 d[0]）来访问第一个元素。索引访问在两端是 O(1) 的，但在中间会慢到 O(n)。对于快速随机访问，请使用列表。

从版本 3.5 开始，双端队列支持 __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'])

deque 技巧

本节展示了使用双端队列的各种方法。

有界长度的双端队列提供了与 Unix 中 tail 过滤器类似的功能：

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

使用双端队列的另一种方法是维护一个最近添加元素的序列，通过右侧追加和左侧弹出实现：

def moving_average(iterable, n=3):
    # moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0
    # https://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

可以使用存储在 deque 中的输入迭代器来实现一个轮询调度器。值从位置零的活动迭代器中产生。如果该迭代器耗尽，可以使用 popleft() 将其移除；否则，可以使用 rotate() 方法将其循环到末尾。

def roundrobin(*iterables):
    "roundrobin('ABC', 'D', 'EF') --> A D E B F C"
    iterators = deque(map(iter, iterables))
    while iterators:
        try:
            while True:
                yield next(iterators[0])
                iterators.rotate(-1)
        except StopIteration:
            # Remove an exhausted iterator.
            iterators.popleft()

rotate() 方法提供了一种实现 deque 切片和删除的方法。例如，一个纯 Python 实现的 del d[n] 依赖于 rotate() 方法来定位要弹出的元素：

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

要实现 deque 切片，可以使用类似的方法，应用 rotate() 将目标元素带到双端队列的左侧。用 popleft() 移除旧条目，用 extend() 添加新条目，然后反转旋转。通过对该方法的微小变化，可以轻松实现 Forth 风格的堆栈操作，如 dup、drop、swap、over、pick、rot 和 roll。

defaultdict 对象

class collections.defaultdict(default_factory=None, /[, ...])

返回一个新的类似字典的对象。defaultdict 是内置 dict 类的子类。它重写了一个方法并增加了一个可写的实例变量。其余功能与 dict 类相同，此处不再赘述。

第一个参数为 default_factory 属性提供初始值；它默认为 None。所有其余参数的处理方式与传递给 dict 构造函数的方式相同，包括关键字参数。

除了标准的 dict 操作外，defaultdict 对象还支持以下方法：

__missing__(key)

如果 default_factory 属性为 None，则此方法会引发一个以 key 为参数的 KeyError 异常。

如果 default_factory 不为 None，它会在不带参数的情况下被调用，为给定的 key 提供一个默认值，这个值会被插入到字典中作为 key 的值，并被返回。

如果调用 default_factory 引发异常，此异常将原样传播。

当请求的键不存在时，dict 类的 __getitem__() 方法会调用此方法；无论它返回什么或引发什么，__getitem__() 都会返回或引发相应的内容。

请注意，除了 __getitem__() 之外的任何操作都不会调用 __missing__()。这意味着 get() 会像普通字典一样返回 None 作为默认值，而不是使用 default_factory。

defaultdict 对象支持以下实例变量：

default_factory

此属性由 __missing__() 方法使用；它从构造函数的第一个参数初始化（如果存在），或者初始化为 None（如果不存在）。

在 3.9 版更改: 添加了合并 (|) 和更新 (|=) 运算符，详见 PEP 584。

defaultdict 示例

使用 list 作为 default_factory，可以轻松地将一系列键值对分组到一个列表字典中：

>>> 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])]

当每个键首次遇到时，它还不在映射中；因此会自动使用 default_factory 函数创建一个条目，该函数返回一个空的 list。list.append() 操作随后将值附加到新列表中。当再次遇到键时，查找将正常进行（返回该键的列表），list.append() 操作将另一个值添加到列表中。这种技术比使用 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 设置为 int，使得 defaultdict 对于计数非常有用（类似于其他语言中的 bag 或 multiset）：

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

当一个字母首次遇到时，它在映射中不存在，因此 default_factory 函数调用 int() 来提供一个默认的零计数。然后，递增操作会为每个字母建立计数。

总是返回零的函数 int() 只是常量函数的一个特例。创建常量函数的一种更快、更灵活的方法是使用 lambda 函数，它可以提供任何常量值（不仅仅是零）：

>>> 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 设置为 set 使得 defaultdict 对于构建集合字典非常有用：

>>> 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})]

namedtuple() 用于创建带命名字段的元组的工厂函数

命名元组为元组中的每个位置赋予意义，并允许编写更具可读性、自文档化的代码。它们可以在任何使用常规元组的地方使用，并且增加了通过名称而不是位置索引访问字段的能力。

collections.namedtuple(typename, field_names, *, rename=False, defaults=None, module=None)

返回一个名为 typename 的新元组子类。这个新的子类用于创建类似元组的对象，这些对象的字段可以通过属性查找以及索引和迭代来访问。该子类的实例还有一个有用的文档字符串（包含 typename 和 field_names）和一个有用的 __repr__() 方法，该方法以 name=value 格式列出元组内容。

field_names 是一个字符串序列，例如 ['x', 'y']。或者，field_names 可以是一个单一的字符串，每个字段名由空格和/或逗号分隔，例如 'x y' 或 'x, y'。

任何有效的 Python 标识符都可以用作字段名，但以下划线开头的名称除外。有效的标识符由字母、数字和下划线组成，但不能以数字或下划线开头，并且不能是关键字，例如 class、for、return、global、pass 或 raise。

如果 rename 为 true，无效的字段名会自动替换为位置名称。例如，['abc', 'def', 'ghi', 'abc'] 会被转换为 ['abc', '_1', 'ghi', '_3']，从而消除了关键字 def 和重复的字段名 abc。

defaults 可以是 None 或一个默认值的可迭代对象。由于具有默认值的字段必须位于任何没有默认值的字段之后，因此 defaults 应用于最右边的参数。例如，如果字段名是 ['x', 'y', 'z']，默认值是 (1, 2)，那么 x 将是必需的参数，y 将默认为 1，z 将默认为 2。

如果定义了 module，命名元组的 __module__ 属性将被设置为该值。

命名元组实例没有每个实例的字典，因此它们是轻量级的，并且比常规元组需要更少的内存。

为了支持 pickle，命名元组类应分配给一个与 typename 相匹配的变量。

在 3.1 版更改: 添加了对 rename 的支持。

在 3.6 版更改: verbose 和 rename 参数变成了仅关键字参数。

在 3.6 版更改: 添加了 module 参数。

在 3.7 版更改: 移除了 verbose 参数和 _source 属性。

在 3.7 版更改: 添加了 defaults 参数和 _field_defaults 属性。

>>> # 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 或 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)

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

classmethod somenamedtuple._make(iterable)

从现有序列或可迭代对象创建新实例的类方法。

>>> t = [11, 22]
>>> Point._make(t)
Point(x=11, y=22)

somenamedtuple._asdict()

返回一个新的 dict，它将字段名映射到它们相应的值：

>>> p = Point(x=11, y=22)
>>> p._asdict()
{'x': 11, 'y': 22}

在 3.1 版更改: 返回一个 OrderedDict 而不是常规的 dict。

在 3.8 版更改: 返回一个常规 dict 而不是 OrderedDict。从 Python 3.7 开始，常规 dict 保证是有序的。如果需要 OrderedDict 的额外功能，建议的补救措施是将结果转换为所需类型：OrderedDict(nt._asdict())。

somenamedtuple._replace(**kwargs)

返回命名元组的一个新实例，用新值替换指定的字段：

>>> p = Point(x=11, y=22)
>>> p._replace(x=33)
Point(x=33, y=22)

>>> for partnum, record in inventory.items():
...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())

命名元组也受通用函数 copy.replace() 的支持。

在 3.13 版更改: 对于无效的关键字参数，引发 TypeError 而不是 ValueError。

somenamedtuple._fields

列出字段名的字符串元组。用于内省和从现有命名元组创建新的命名元组类型。

>>> p._fields            # view the field names
('x', 'y')

>>> 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)

somenamedtuple._field_defaults

将字段名映射到默认值的字典。

>>> Account = namedtuple('Account', ['type', 'balance'], defaults=[0])
>>> Account._field_defaults
{'balance': 0}
>>> Account('premium')
Account(type='premium', balance=0)

要检索名称存储在字符串中的字段，请使用 getattr() 函数：

>>> getattr(p, 'x')
11

要将字典转换为命名元组，请使用双星号运算符（如 解包参数列表 中所述）：

>>> d = {'x': 11, 'y': 22}
>>> Point(**d)
Point(x=11, y=22)

由于命名元组是常规的 Python 类，因此使用子类来添加或更改功能非常容易。以下是如何添加一个计算字段和一个固定宽度的打印格式：

>>> class Point(namedtuple('Point', ['x', 'y'])):
...     __slots__ = ()
...     @property
...     def hypot(self):
...         return (self.x ** 2 + self.y ** 2) ** 0.5
...     def __str__(self):
...         return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)

>>> for p in Point(3, 4), Point(14, 5/7):
...     print(p)
Point: x= 3.000  y= 4.000  hypot= 5.000
Point: x=14.000  y= 0.714  hypot=14.018

上面显示的子类将 __slots__ 设置为空元组。这有助于通过防止创建实例字典来保持较低的内存需求。

子类化对于添加新的、存储的字段没有用处。相反，只需从 _fields 属性创建一个新的命名元组类型：

>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))

可以通过直接赋值给 __doc__ 字段来自定义文档字符串：

>>> Book = namedtuple('Book', ['id', 'title', 'authors'])
>>> Book.__doc__ += ': Hardcover book in active collection'
>>> Book.id.__doc__ = '13-digit ISBN'
>>> Book.title.__doc__ = 'Title of first printing'
>>> Book.authors.__doc__ = 'List of authors sorted by last name'

在 3.5 版更改: 属性文档字符串变为可写。

参见

• 请参阅 typing.NamedTuple，了解为命名元组添加类型提示的方法。它还提供了一种使用 class 关键字的优雅表示法。

  class Component(NamedTuple):
      part_number: int
      weight: float
      description: Optional[str] = None
  

• 有关基于底层字典而不是元组的可变命名空间，请参见 types.SimpleNamespace()。

• dataclasses 模块提供了一个装饰器和函数，用于自动向用户定义的类添加生成的特殊方法。

OrderedDict 对象

有序字典就像常规字典一样，但具有一些与排序操作相关的额外功能。现在，由于内置的 dict 类获得了记住插入顺序的能力（这种新行为在 Python 3.7 中得到保证），它们的重要性有所降低。

与 dict 的一些差异仍然存在：

• 常规的 dict 设计用于非常擅长映射操作。跟踪插入顺序是次要的。

• OrderedDict 被设计为擅长重新排序操作。空间效率、迭代速度和更新操作的性能是次要的。

• OrderedDict 算法比 dict 更能处理频繁的重新排序操作。如下面的示例所示，这使其适用于实现各种类型的 LRU 缓存。

• OrderedDict 的相等性操作会检查顺序是否匹配。

  常规 dict 可以通过 p == q and all(k1 == k2 for k1, k2 in zip(p, q)) 模拟对顺序敏感的相等性测试。

• OrderedDict 的 popitem() 方法具有不同的签名。它接受一个可选参数来指定弹出哪个项。

  常规 dict 可以通过 d.popitem() 模拟 OrderedDict 的 od.popitem(last=True)，这保证会弹出最右边（最后）的项。

  常规 dict 可以通过 (k := next(iter(d)), d.pop(k)) 模拟 OrderedDict 的 od.popitem(last=False)，如果存在，这将返回并移除最左边（第一个）的项。

• OrderedDict 有一个 move_to_end() 方法，可以高效地将一个元素重新定位到端点。

  常规 dict 可以通过 d[k] = d.pop(k) 模拟 OrderedDict 的 od.move_to_end(k, last=True)，这将把键及其关联的值移动到最右边（最后）的位置。

  常规 dict 没有与 OrderedDict 的 od.move_to_end(k, last=False) 等效的高效方法，该方法将键及其关联的值移动到最左边（第一个）的位置。

• 在 Python 3.8 之前，dict 缺少一个 __reversed__() 方法。

class collections.OrderedDict([items])

返回一个 dict 子类的实例，该子类具有专门用于重新排列字典顺序的方法。

在 3.1 版本加入。

popitem(last=True)

有序字典的 popitem() 方法返回并移除一个 (键, 值) 对。如果 last 为 true，则按 LIFO 顺序返回，如果为 false，则按 FIFO 顺序返回。

move_to_end(key, last=True)

将一个现有的 key 移动到有序字典的任一端。如果 last 为 true（默认值），则项被移动到右端，如果 last 为 false，则移动到开头。如果 key 不存在，则引发 KeyError。

>>> d = OrderedDict.fromkeys('abcde')
>>> d.move_to_end('b')
>>> ''.join(d)
'acdeb'
>>> d.move_to_end('b', last=False)
>>> ''.join(d)
'bacde'

在 3.2 版本加入。

除了通常的映射方法外，有序字典还支持使用 reversed() 进行反向迭代。

OrderedDict 对象之间的相等性测试是顺序敏感的，大致等价于 list(od1.items())==list(od2.items())。

OrderedDict 对象和其他 Mapping 对象之间的相等性测试是顺序不敏感的，就像常规字典一样。这允许 OrderedDict 对象在任何使用常规字典的地方被替换使用。

在 3.5 版更改: OrderedDict 的项、键和值的 视图 现在支持使用 reversed() 进行反向迭代。

在 3.6 版更改: 随着 PEP 468 的接受，传递给 OrderedDict 构造函数及其 update() 方法的关键字参数会保留其顺序。

在 3.9 版更改: 添加了在 PEP 584 中指定的合并（|）和更新（|=）运算符。

OrderedDict 示例与配方

可以很轻松地创建一个有序字典的变种，使其记住键被 *最后一次* 插入的顺序。如果一个新条目覆盖了现有条目，则原始插入位置会被更改并移至末尾。

class LastUpdatedOrderedDict(OrderedDict):
    'Store items in the order the keys were last added'

    def __setitem__(self, key, value):
        super().__setitem__(key, value)
        self.move_to_end(key)

一个 OrderedDict 在实现 functools.lru_cache() 的变种时也会很有用。

from collections import OrderedDict
from time import time

class TimeBoundedLRU:
    "LRU Cache that invalidates and refreshes old entries."

    def __init__(self, func, maxsize=128, maxage=30):
        self.cache = OrderedDict()      # { args : (timestamp, result)}
        self.func = func
        self.maxsize = maxsize
        self.maxage = maxage

    def __call__(self, *args):
        if args in self.cache:
            self.cache.move_to_end(args)
            timestamp, result = self.cache[args]
            if time() - timestamp <= self.maxage:
                return result
        result = self.func(*args)
        self.cache[args] = time(), result
        if len(self.cache) > self.maxsize:
            self.cache.popitem(last=False)
        return result

class MultiHitLRUCache:
    """ LRU cache that defers caching a result until
        it has been requested multiple times.

        To avoid flushing the LRU cache with one-time requests,
        we don't cache until a request has been made more than once.

    """

    def __init__(self, func, maxsize=128, maxrequests=4096, cache_after=1):
        self.requests = OrderedDict()   # { uncached_key : request_count }
        self.cache = OrderedDict()      # { cached_key : function_result }
        self.func = func
        self.maxrequests = maxrequests  # max number of uncached requests
        self.maxsize = maxsize          # max number of stored return values
        self.cache_after = cache_after

    def __call__(self, *args):
        if args in self.cache:
            self.cache.move_to_end(args)
            return self.cache[args]
        result = self.func(*args)
        self.requests[args] = self.requests.get(args, 0) + 1
        if self.requests[args] <= self.cache_after:
            self.requests.move_to_end(args)
            if len(self.requests) > self.maxrequests:
                self.requests.popitem(last=False)
        else:
            self.requests.pop(args, None)
            self.cache[args] = result
            if len(self.cache) > self.maxsize:
                self.cache.popitem(last=False)
        return result

UserDict 对象

类 UserDict 是对字典对象的包装。由于现在可以直接从 dict 继承，这个类的必要性已部分被取代；但是，这个类用起来可能更容易，因为其底层的字典可以作为一个属性来访问。

class collections.UserDict([initialdata])

模拟一个字典的类。实例的内容存放在一个常规字典中，该字典可以通过 UserDict 实例的 data 属性访问。如果提供了 initialdata，data 会用其内容进行初始化；请注意，不会保留对 initialdata 的引用，这允许它被用于其他目的。

除了支持映射的方法和操作外，UserDict 实例还提供了以下属性：

data

一个用于存储 UserDict 类内容的真实字典。

UserList 对象

这个类是对列表对象的包装。对于自定义的类列表（list-like）的类来说，它是一个很有用的基类，可以继承它并重写现有方法或添加新方法。通过这种方式，可以为列表添加新的行为。

由于现在可以直接从 list 继承，这个类的必要性已部分被取代；但是，这个类用起来可能更容易，因为其底层的列表可以作为一个属性来访问。

class collections.UserList([list])

模拟一个列表的类。实例的内容存放在一个常规列表中，该列表可以通过 UserList 实例的 data 属性访问。实例的内容最初被设置为 list 的一个副本，默认为空列表 []。list 可以是任何可迭代对象，例如一个真实的 Python 列表或一个 UserList 对象。

除了支持可变序列的方法和操作外，UserList 实例还提供了以下属性：

data

一个用于存储 UserList 类内容的真实 list 对象。

子类化要求：UserList 的子类需要提供一个构造函数，该构造函数可以无参数调用，也可以带一个参数调用。返回新序列的列表操作会尝试创建实际实现类的实例。为此，它假定构造函数可以用一个参数来调用，这个参数是一个用作数据源的序列对象。

如果派生类不希望遵循此要求，则需要重写该类支持的所有特殊方法；有关在这种情况下需要提供哪些方法的信息，请查阅源代码。

UserString 对象

类 UserString 是对字符串对象的包装。由于现在可以直接从 str 继承，这个类的必要性已部分被取代；但是，这个类用起来可能更容易，因为其底层的字符串可以作为一个属性来访问。

class collections.UserString(seq)

模拟一个字符串对象的类。实例的内容存放在一个常规字符串对象中，该对象可以通过 UserString 实例的 data 属性访问。实例的内容最初被设置为 seq 的一个副本。seq 参数可以是任何可以使用内置 str() 函数转换为字符串的对象。

除了支持字符串的方法和操作外，UserString 实例还提供了以下属性：

data

一个用于存储 UserString 类内容的真实 str 对象。

在 3.5 版更改: 新增方法 __getnewargs__、 __rmod__、 casefold、 format_map、 isprintable 和 maketrans。