collections ---容器数据类型

源代码： Lib/collections/__init__.py

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

namedtuple()

用于创建具有命名字段的元组子类的factory函数

deque

列表状容器，两端具有快速附加和弹出

ChainMap

用于创建多个映射的单个视图的类似dict的类

Counter

用于计算hash对象的dict子类

OrderedDict

记忆订单条目的dict子类被添加

defaultdict

调用factory函数以提供缺少的值的dict子类

UserDict

封装字典对象以便于dict子类化

UserList

围绕列表对象进行封装，以便于列表子类化

UserString

围绕字符串对象进行封装，以便于字符串子类化

ChainMap 物体

3.3 新版功能.

A ChainMap 类用于快速链接多个映射，以便将它们视为单个单元。它通常比创建新字典和运行多个 update() 调用。

类可用于模拟嵌套范围，并在模板化中很有用。

class collections.ChainMap(*maps)

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

基础映射存储在列表中。该列表是公共的，可以使用 maps 属性。没有其他州。

查找依次搜索基础映射，直到找到一个键。相反，写入、更新和删除只在第一个映射上操作。

A ChainMap 通过引用合并基础映射。因此，如果更新了其中一个底层映射，那么这些更改将反映在 ChainMap .

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

maps

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

new_child(m=None)

返回新的 ChainMap 包含一个新映射，后跟当前实例中的所有映射。如果 m 如果指定，它将成为映射列表前面的新映射；如果未指定，则使用空dict，以便调用 d.new_child() 相当于： ChainMap({{}}, *d.maps) . 此方法用于创建子文本，这些子文本可以在不更改任何父映射中的值的情况下进行更新。

在 3.4 版更改: 可选的 m 已添加参数。

parents

返回新的 ChainMap 包含当前实例中除第一个映射以外的所有映射。这对于跳过搜索中的第一个映射很有用。用例与 nonlocal 关键字使用 nested scopes . 用例也与内置的用例类似 super() 功能。对…的参考 d.parents 相当于： ChainMap(*d.maps[1:]) .

注：a的迭代顺序 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])

A Counter 是一个 dict 用于计算hash对象的子类。它是一个集合，元素存储为字典键，其计数存储为字典值。计数可以是任何整数值，包括零计数或负计数。这个 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

计数器对象有一个字典接口，除非它们为缺少的项返回零计数，而不是引发 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 继承了记忆插入顺序的功能。上的数学运算 计数器 对象还保留顺序。结果的排序取决于在左操作数中第一次遇到元素的时间，然后是按照在右操作数中遇到的顺序。

计数器对象支持三种方法，而不是所有字典都支持的方法：

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() 返回 all 计数器中的元素。计数相等的元素按遇到的第一个顺序排列：

>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
subtract([iterable-or-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 新版功能.

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

fromkeys(iterable)

没有为实现此类方法 Counter 物体。

update([iterable-or-mapping])

元素从 可迭代的 或从另一个添加 映射 （或计数器）。类似于 dict.update() 但是增加计数而不是取代它们。此外， 可迭代的 应为元素序列，而不是 (key, value) 对。

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

3.10 新版功能: 添加了丰富的比较操作

在 3.10 版更改: 在等式测试中，缺少的元素被视为具有零计数。从前， Counter(a=3) 和 Counter(a=3, b=0) 被认为是与众不同的。

使用的常见模式 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

提供了几种用于组合的数学运算 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 = Counter(a=2, b=-4)
>>> +c
Counter({'a': 2})
>>> -c
Counter({'b': 4})

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

注解

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

  • 这个 Counter 类本身是字典子类，对其键和值没有限制。这些值是表示计数的数字，但是 能够 在值字段中存储任何内容。

  • 这个 most_common() 方法只要求值是可排序的。

  • 用于就地操作，如 c[key] += 1 值类型只需要支持加减。所以分数、浮点数和小数可以工作，并且支持负值。同样的道理也适用于 update() 和 subtract() 允许输入和输出均为负值和零值。

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

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

参见

  • Bag class 在SimalTalk中。

  • 维基百科条目 Multisets .

  • C++ multisets 带示例的教程。

  • 有关多集及其用例的数学运算，请参见 克努斯，唐纳德。计算机编程艺术第二卷第4.6.3节练习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对象（使用 append() ）数据来自 可迭代的 . 如果 可迭代的 未指定，新deque为空。

deques是堆栈和队列的泛化（名称发音为“deck”，是“双头队列”的缩写）。Deques支持线程安全、内存高效的附加和来自Deque任一侧的pop，两个方向的O（1）性能大致相同。

尽管如此 list 对象支持类似的操作，它们针对快速的固定长度操作进行了优化，并为 pop(0) 和 insert(0, v) 同时更改基础数据表示形式的大小和位置的操作。

如果 麦克伦 未指定或 None ，deques可以增长到任意长度。否则，deque被限定为指定的最大长度。一旦有界长度deque满了，当添加新项时，从另一端丢弃相应数量的项。有界长度Deques提供类似于 tail 在Unix中过滤。它们还可用于跟踪事务和其他仅关注最近活动的数据池。

Deque对象支持以下方法：

append(x)

添加 x 在德克河的右侧。

appendleft(x)

添加 x 在德克河的左侧。

clear()

从DEQUE中删除所有元素，保留长度0。

copy()

创建一个deque的浅拷贝。

3.5 新版功能.

count(x)

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

3.2 新版功能.

extend(iterable)

通过从iterable参数附加元素来扩展deque的右侧。

extendleft(iterable)

通过附加元素来扩展deque的左侧 可迭代的 . 注意，左附加的序列会导致ITerable参数中元素的顺序颠倒。

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

返回的位置 x 在deque中（在索引处或索引后 开始 在索引之前 stop ）返回第一个匹配项或引发项 ValueError 如果找不到。

3.5 新版功能.

insert(i, x)

插入 x 在适当的位置进入deque i .

如果插入将导致有界deque增长超过 麦克伦 ，一个 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 新版功能.

除此之外，Deques还支持迭代、酸洗、 len(d) ， reversed(d) ， copy.copy(d) ， copy.deepcopy(d) ，成员资格测试 in 运算符和下标引用，例如 d[0] 访问第一个元素。索引访问在两端是O（1），但在中间是O（n）。要快速随机访问，请使用列表。

从3.5版开始，Deques支持 __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 秘诀

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

有界长度Deques提供类似于 tail Unix中的筛选器：

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

使用deques的另一种方法是通过在右边附加并在左边弹出来保持最近添加的元素的序列：

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

A round-robin scheduler 可以使用存储在 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() ，然后反转旋转。对于这种方法的微小变化，很容易实现四样式的堆栈操作，例如 dup ， drop ， swap ， over ， pick ， rot 和 roll .

defaultdict 物体

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

返回类似字典的新对象。 defaultdict 是内置的子类 dict 类。它重写一个方法并添加一个可写实例变量。其余功能与 dict 类，此处未记录。

第一个参数提供 default_factory 属性；默认为 None . 所有剩余的参数将被视为与传递给 dict 构造函数，包括关键字参数。

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

__missing__(key)

如果 default_factory 属性是 None 这引发了 KeyError 例外 key 作为参数。

如果 default_factory 不是 None ，在不带参数的情况下调用它以为给定的 key ，此值插入到字典中 key 然后返回。

如果调用 default_factory 引发异常。此异常未更改传播。

此方法由 __getitem__() 方法 dict 当找不到请求的键时初始化；它返回或引发的任何内容都将由返回或引发 __getitem__() .

注意 __missing__() 是 not 除此之外还需要任何操作 __getitem__() . 这意味着 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 用于计数（如其他语言的包或多集）：

>>> 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() 具有命名字段的元组的factory函数

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

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

返回名为的新元组子类 类别名 . 新的子类用于创建类元组的对象，这些对象具有可通过属性查找访问的字段以及可索引和可iterable。子类的实例还具有一个有用的docstring（带有typename和field_名称）和一个有用的 __repr__() 方法，该方法列出 name=value 格式。

这个 field_names 是字符串序列，例如 ['x', 'y'] .或者， field_names 例如，可以是单个字符串，每个字段名之间用空格和/或逗号分隔 'x y' 或 'x, y' .

除以下划线开头的名称外，任何有效的python标识符都可以用于fieldname。有效标识符由字母、数字和下划线组成，但不能以数字或下划线开头，并且不能是 keyword 如 classes ， for ， 返回 ， 全球的 ， pass 或 引发 .

如果 重命名 为true，无效的字段名将自动替换为位置名。例如， ['abc', 'def', 'ghi', 'abc'] 转换为 ['abc', '_1', 'ghi', '_3'] ，删除关键字 def 和重复的字段名 abc .

默认值 可以是 None 或 iterable 默认值。由于具有默认值的字段必须位于没有默认值的任何字段之后，因此 默认值 应用于最右侧的参数。例如，如果字段名是 ['x', 'y', 'z'] 默认值是 (1, 2) 然后 x 将是必需的参数， y 将默认为 1 和 z 将默认为 2 .

如果 模块 定义了 __module__ 命名元组的属性设置为该值。

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

若要支持酸选，应将命名元组类赋给匹配的变量 类型名称 。

在 3.1 版更改: 为添加了支持 重命名 .

在 3.6 版更改: 这个 verbose 和 重命名 参数变为 keyword-only arguments .

在 3.6 版更改: 增加了 模块 参数。

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

在 3.7 版更改: 增加了 默认值 参数和 _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)

从现有序列或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())
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 版更改: DocStrings属性变为可写。

参见

  • 见 typing.NamedTuple 为命名元组添加类型提示的方法。它还提供了一个优雅的符号，使用 class 关键词：

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

  • 见 types.SimpleNamespace() 基于基础字典而不是元组的可变命名空间。

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

OrderedDict 物体

排序字典与常规字典一样，但具有一些与排序操作相关的额外功能。由于内置的 dict 类获得了记住插入顺序的能力（这一新行为在Python3.7中得到了保证）。

与 dict 仍然存在：

  • 规则的 dict 旨在非常擅长地图绘制操作。跟踪插入顺序是次要的。

  • 这个 OrderedDict 旨在擅长重新排序操作。空间效率、迭代速度和更新操作的性能是次要的。

  • 算法上， OrderedDict 能够更好地处理频繁的重新排序操作 dict .这使得它适合跟踪最近的访问（例如 LRU cache ）

  • 的相等运算 OrderedDict 检查匹配的订单。

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

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

  • 在python 3.8之前， dict 缺少A __reversed__() 方法。

class collections.OrderedDict([items])

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

3.1 新版功能.

popitem(last=True)

这个 popitem() 方法返回并删除（键、值）对。成对的返回 LIFO 订购如果 last 是真的还是 FIFO 如果错误，则命令。

move_to_end(key, last=True)

移动现有 key 到有序字典的两端。如果 last 是真的（默认值），如果 last 是假的。引发 KeyError 如果 key 不存在：：

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

3.2 新版功能.

除了通常的映射方法外，有序字典还支持使用 reversed() .

平等性测试 OrderedDict 对象是顺序敏感的，并且实现为 list(od1.items())==list(od2.items()) . 平等性测试 OrderedDict 对象和其他 Mapping 对象与常规字典一样不区分顺序。这允许 OrderedDict 任何使用常规字典的地方都要替换的对象。

在 3.5 版更改: 项、键和值 views 属于 OrderedDict 现在支持使用 reversed() .

在 3.6 版更改: 接受 PEP 468 ，对于传递给 OrderedDict 施工单位及其 update() 方法。

在 3.9 版更改: 添加的合并 (| )和更新 (|= )运算符，在中指定 PEP 584 .

OrderedDict 示例和配方

很容易创建一个有序的字典变量来记住键的顺序 last 插入的。如果新条目覆盖现有条目，则原始插入位置将更改并移动到末尾：

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

class LRU(OrderedDict):
    'Limit size, evicting the least recently looked-up key when full'

    def __init__(self, maxsize=128, /, *args, **kwds):
        self.maxsize = maxsize
        super().__init__(*args, **kwds)

    def __getitem__(self, key):
        value = super().__getitem__(key)
        self.move_to_end(key)
        return value

    def __setitem__(self, key, value):
        if key in self:
            self.move_to_end(key)
        super().__setitem__(key, value)
        if len(self) > self.maxsize:
            oldest = next(iter(self))
            del self[oldest]

UserDict 物体

类， UserDict 充当字典对象的封装器。这个类的需求已经部分地被直接从 dict ；但是，这个类可以更容易地使用，因为基础字典可以作为一个属性进行访问。

class collections.UserDict([initialdata])

模拟字典的类。实例的内容保存在常规字典中，可以通过 data 属性 UserDict 实例。如果 初始数据 提供， data 是用其内容初始化的；请注意 初始数据 不会保留，允许用于其他目的。

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

data

用于存储 UserDict 类。

UserList 物体

这个类充当列表对象的封装器。对于您自己的列表类类类，它是一个有用的基类，这些类可以从它们继承并重写现有方法或添加新方法。这样，就可以向列表中添加新的行为。

这个类的需求已经部分地被直接从 list 但是，这个类可以更容易地使用，因为底层列表可以作为一个属性进行访问。

class collections.UserList([list])

模拟列表的类。实例的内容保存在常规列表中，可以通过 data 属性 UserList 实例。实例的内容最初设置为 list ，默认为空列表 [] . list 可以是任何iterable，例如真正的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 .