collections — 容器数据类型

源代码: Lib/collections/__init__.py


这个模块实现了专门的容器数据类型,提供了 Python 通用内置容器的替代方案,dictlistsettuple

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,其中包含当前实例中的所有映射,但不包括第一个映射。这对于跳过搜索中的第一个映射很有用。用例类似于 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 中所指定。

另请参阅

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

Counterdict 的子类,用于计算 可哈希 对象。它是一个集合,其中元素存储为字典键,其计数存储为字典值。计数允许为任何整数值,包括零或负计数。Counter 类类似于其他语言中的包或多重集。

元素从 *iterable* 中计数,或从另一个 *mapping*(或计数器)初始化

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

返回一个迭代器,该迭代器遍历元素,并将其重复其计数次数。元素按照首次遇到的顺序返回。如果元素的计数小于 1,则 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*(或计数器)中减去。类似于 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*(或计数器)中添加。类似于 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 类

  • Wikipedia 中关于 多重集 的条目。

  • 带有示例的 C++ 多重集 教程。

  • 有关多重集的数学运算及其使用案例,请参阅 *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]])

返回一个新的 deque 对象,该对象使用来自 iterable 的数据从左到右(使用 append())初始化。如果未指定 iterable,则新的 deque 为空。

Deque 是栈和队列的概括(名称发音为“deck”,是“双端队列”的缩写)。 Deque 支持线程安全的、内存高效的从 deque 的任一侧追加和弹出,在任一方向上的性能都近似为 *O*(1)。

虽然 list 对象支持类似的操作,但它们针对快速固定长度操作进行了优化,并且对于更改底层数据表示的大小和位置的 pop(0)insert(0, v) 操作会产生 *O*(*n*) 的内存移动成本。

如果未指定 maxlen 或为 None,则 deque 可以增长到任意长度。 否则,deque 将被限制为指定的最大长度。 一旦有界长度的 deque 已满,当添加新项时,会从另一端丢弃相应数量的项。 有界长度的 deque 提供的功能类似于 Unix 中的 tail 过滤器。 它们还可用于跟踪事务和其他仅对最近活动感兴趣的数据池。

Deque 对象支持以下方法

append(x)

x 添加到 deque 的右侧。

appendleft(x)

x 添加到 deque 的左侧。

clear()

从 deque 中删除所有元素,使其长度为 0。

copy()

创建 deque 的浅拷贝。

在版本 3.5 中添加。

count(x)

计算等于 x 的 deque 元素的数量。

3.2 版本新增。

extend(iterable)

通过从可迭代参数追加元素来扩展 deque 的右侧。

extendleft(iterable)

通过从 iterable 追加元素来扩展 deque 的左侧。 请注意,左追加的序列会导致可迭代参数中元素的顺序反转。

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

返回 x 在 deque 中的位置(在索引 start 处或之后且在索引 stop 之前)。 返回第一个匹配项,如果未找到则引发 ValueError

在版本 3.5 中添加。

insert(i, x)

x 插入到 deque 中位置 i 处。

如果插入会导致有界 deque 增长超过 maxlen,则会引发 IndexError

在版本 3.5 中添加。

pop()

从 deque 的右侧删除并返回一个元素。 如果不存在任何元素,则会引发 IndexError

popleft()

从 deque 的左侧删除并返回一个元素。 如果不存在任何元素,则会引发 IndexError

remove(value)

删除 value 的第一个出现。 如果未找到,则会引发 ValueError

reverse()

反转 deque 的元素,然后在原地返回 None

3.2 版本新增。

rotate(n=1)

将 deque 向右旋转 n 步。 如果 n 为负数,则向左旋转。

当 deque 不为空时,向右旋转一步等效于 d.appendleft(d.pop()),向左旋转一步等效于 d.append(d.popleft())

Deque 对象还提供一个只读属性

maxlen

deque 的最大大小,如果无界则为 None

3.1 版本新增。

除上述之外,deque 还支持迭代、pickle、len(d)reversed(d)copy.copy(d)copy.deepcopy(d)、使用 in 运算符的成员资格测试以及诸如 d[0] 之类的下标引用来访问第一个元素。索引访问在两端为 *O*(1),但在中间会减慢到 *O*(*n*)。对于快速随机访问,请改用列表。

从版本 3.5 开始,deque 支持 __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 技巧

本节展示了使用 deque 的各种方法。

有界长度的 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)

使用 deque 的另一种方法是通过追加到右侧并弹出到左侧来维护最近添加的元素序列

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 切片和删除的方法。例如,del d[n] 的纯 Python 实现依赖于 rotate() 方法来定位要弹出的元素

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

要实现 deque 切片,可以使用类似的方法,应用 rotate() 将目标元素移动到双端队列的左侧。使用 popleft() 删除旧条目,使用 extend() 添加新条目,然后反转旋转。对该方法进行少量修改,可以轻松实现 Forth 风格的堆栈操作,例如 dupdropswapoverpickrotroll

defaultdict 对象

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

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

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

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

__missing__(key)

如果 default_factory 属性为 None,则会引发一个 KeyError 异常,其中 key 作为参数。

如果 default_factory 不为 None,则会调用它(不带参数)以提供给定 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])]

当首次遇到每个键时,它尚未在映射中;因此,使用返回空 listdefault_factory 函数自动创建一个条目。然后,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 可用于计数(类似于其他语言中的包或多重集)

>>> 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* 这样的 keyword

如果 *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)

命名元组特别适用于为 csvsqlite3 模块返回的结果元组分配字段名称。

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 开始,保证常规字典是有序的。如果需要 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)) 来模拟对顺序敏感的相等性测试。

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

    常规的 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() 方法返回并删除一个 (key, value) 对。如果 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])

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

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

data

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

UserList 对象

此类充当列表对象的包装器。它是一个有用的基类,供您自己的类列表继承并覆盖现有方法或添加新方法。 通过这种方式,可以向列表添加新行为。

直接从 list 继承的能力部分取代了对此类的需求;但是,这个类更容易使用,因为底层列表可以作为属性访问。

class collections.UserList([list])

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

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

data

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

子类化要求:UserList 的子类应提供一个可以使用零个参数或一个参数调用的构造函数。返回新序列的列表操作尝试创建实际实现类的实例。为此,它假设可以使用一个参数(即用作数据源的序列对象)调用构造函数。

如果派生类不希望遵守此要求,则需要重写此类支持的所有特殊方法;请查阅源代码以获取有关在这种情况下需要提供的方法的信息。

UserString 对象

UserString 充当字符串对象的包装器。直接从 str 继承的能力部分取代了对此类的需求;但是,这个类更容易使用,因为底层字符串可以作为属性访问。

class collections.UserString(seq)

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

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

data

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

在 3.5 版本中变更: 新增方法 __getnewargs__, __rmod__, casefold, format_map, isprintable, 和 maketrans.