`collections` — 容器資料型別¶

這個模組實現了專門的容器資料型別，提供了 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，其中包含當前例項中的所有對映，但不包括第一個對映。這對於跳過搜尋中的第一個對映很有用。用例類似於 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 屬性類似的上下文的推送和彈出功能。
巢狀上下文配方具有控制寫入和其他修改是僅應用於第一個對映還是應用於鏈中的任何對映的選項。
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 類類似於其他語言中的包或多重集。

元素從 *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 風格的堆疊操作，例如 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，則會引發一個 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])]

當首次遇到每個鍵時，它尚未在對映中；因此，使用返回空 list 的 default_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)

命名元組特別適用於為 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 開始，保證常規字典是有序的。如果需要 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() 方法返回並刪除一個 (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.

`collections` — 容器資料型別¶

`ChainMap` 物件¶

`ChainMap` 示例和配方¶

`Counter` 物件¶

`deque` 物件¶

`deque` 技巧¶

`defaultdict` 物件¶

`defaultdict` 示例¶

`namedtuple()` 用於建立帶有命名欄位的元組的工廠函式¶

`OrderedDict` 物件¶

`OrderedDict` 示例和用法¶

`UserDict` 物件¶

`UserList` 物件¶

`UserString` 物件¶

目錄

上一個主題

下一個主題

本頁

collections — 容器資料型別¶

ChainMap 物件¶

ChainMap 示例和配方¶

Counter 物件¶

deque 物件¶

deque 技巧¶

defaultdict 物件¶

defaultdict 示例¶

namedtuple() 用於建立帶有命名欄位的元組的工廠函式¶

OrderedDict 物件¶

OrderedDict 示例和用法¶

UserDict 物件¶

UserList 物件¶

UserString 物件¶

`collections` — 容器資料型別¶

`ChainMap` 物件¶

`ChainMap` 示例和配方¶

`Counter` 物件¶

`deque` 物件¶

`deque` 技巧¶

`defaultdict` 物件¶

`defaultdict` 示例¶

`namedtuple()` 用於建立帶有命名欄位的元組的工廠函式¶

`OrderedDict` 物件¶

`OrderedDict` 示例和用法¶

`UserDict` 物件¶

`UserList` 物件¶

`UserString` 物件¶