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。