collections
— 容器数据类型
¶
源代码：
Lib/collections/__init__.py
此模块实现专用容器数据类型，提供备选为 Python 一般目的内置容器
dict
,
list
,
set
，和
tuple
.
Added in version 3.3.
A
ChainMap
类是为快速链接很多映射而提供的，因此可以将它们视为单个单元。它通常快得多，比创建新字典并运行多个
update()
调用。
此类可以用于模拟嵌套作用域，且在模板中很有用。
-
class
集合。
ChainMap
(
*
maps
)
¶
-
A
ChainMap
将多个字典 (或其它映射) 分组在一起，以创建单个、可更新视图。若没有
maps
被指定，将提供单个空字典，以便新链始终至少拥有一个映射。
底层映射存储在列表中。列表是公共的，且访问 (或更新) 可以使用
maps
属性。没有其它状态。
依次查找搜索底层映射，直到找到键。相比之下，写入、更新及删除仅运转于第一映射。
A
ChainMap
通过引用吸收底层映射。因此，如果某个底层映射获得更新，这些改变将反映在
ChainMap
.
通常支持所有字典方法。此外，还有
maps
属性、用于创建新的子上下文的方法、及用于访问所有映射 (除第 1 映射外) 的特性：
-
maps
¶
-
A user updateable list of mappings. The list is ordered from first-searched to last-searched. It is the only stored state and can be modified to change which mappings are searched. The list should always contain at least one mapping.
-
new_child
(
m
=
None
,
**
kwargs
)
¶
-
返回新的
ChainMap
containing a new map followed by all of the maps in the current instance. If
m
is specified, it becomes the new map at the front of the list of mappings; if not specified, an empty dict is used, so that a call to
d.new_child()
相当于：
ChainMap({}, *d.maps)
. If any keyword arguments are specified, they update passed map or new empty dict. This method is used for creating subcontexts that can be updated without altering values in any of the parent mappings.
3.4 版改变：
可选
m
参数被添加。
3.10 版改变：
Keyword arguments support was added.
-
parents
¶
-
特性返回新
ChainMap
containing all of the maps in the current instance except the first one. This is useful for skipping the first map in the search. Use cases are similar to those for the
nonlocal
keyword used in
nested scopes
. The use cases also parallel those for the built-in
super()
function. A reference to
d.parents
相当于：
ChainMap(*d.maps[1:])
.
Note, the iteration order of a
ChainMap
is determined by scanning the mappings last to first:
>>> baseline = {'music': 'bach', 'art': 'rembrandt'}
>>> adjustments = {'art': 'van gogh', 'opera': 'carmen'}
>>> list(ChainMap(adjustments, baseline))
['music', 'art', 'opera']
This gives the same ordering as a series of
dict.update()
calls starting with the last mapping:
>>> combined = baseline.copy()
>>> combined.update(adjustments)
>>> list(combined)
['music', 'art', 'opera']
3.9 版改变：
添加支持
|
and
|=
operators, specified in
PEP 584
.
This section shows various approaches to working with chained maps.
Example of simulating Python’s internal lookup chain:
import builtins
pylookup = ChainMap(locals(), globals(), vars(builtins))
Example of letting user specified command-line arguments take precedence over environment variables which in turn take precedence over default values:
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'])
Example patterns for using the
ChainMap
class to simulate nested contexts:
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
The
ChainMap
class only makes updates (writes and deletions) to the first mapping in the chain while lookups will search the full chain. However, if deep writes and deletions are desired, it is easy to make a subclass that updates keys found deeper in the chain:
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'})
计数器工具的提供以支持方便、快速计数。例如：
>>> # 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
集合。
Counter
(
[
iterable-or-mapping
]
)
¶
-
A
Counter
是
dict
subclass for counting
hashable
objects. It is a collection where elements are stored as dictionary keys and their counts are stored as dictionary values. Counts are allowed to be any integer value including zero or negative counts. The
Counter
类类似于其它语言中的 bag 或 multiset。
元素的计数来自
iterable
或初始化自另一
映射
(或计数器)：
>>> 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 objects have a dictionary interface except that they return a zero count for missing items instead of raising a
KeyError
:
>>> c = Counter(['eggs', 'ham'])
>>> c['bacon'] # count of a missing element is zero
0
Setting a count to zero does not remove an element from a counter. Use
del
to remove it entirely:
>>> c['sausage'] = 0 # counter entry with a zero count
>>> del c['sausage'] # del actually removes the entry
Added in version 3.1.
3.7 版改变：
作为
dict
子类，
Counter
inherited the capability to remember insertion order. Math operations on
Counter
objects also preserve order. Results are ordered according to when an element is first encountered in the left operand and then by the order encountered in the right operand.
Counter objects support additional methods beyond those available for all dictionaries:
-
elements
(
)
¶
-
Return an iterator over elements repeating each as many times as its count. Elements are returned in the order first encountered. If an element’s count is less than one,
elements()
will ignore it.
>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> sorted(c.elements())
['a', 'a', 'a', 'a', 'b', 'b']
-
most_common
(
[
n
]
)
¶
-
Return a list of the
n
most common elements and their counts from the most common to the least. If
n
被省略或
None
,
most_common()
返回
all
elements in the counter. Elements with equal counts are ordered in the order first encountered:
>>> Counter('abracadabra').most_common(3)
[('a', 5), ('b', 2), ('r', 2)]
-
subtract
(
[
iterable-or-mapping
]
)
¶
-
Elements are subtracted from an
iterable
or from another
映射
(or counter). Like
dict.update()
but subtracts counts instead of replacing them. Both inputs and outputs may be zero or negative.
>>> 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})
Added in version 3.2.
-
total
(
)
¶
-
Compute the sum of the counts.
>>> c = Counter(a=10, b=5, c=0)
>>> c.total()
15
3.10 版添加。
The usual dictionary methods are available for
Counter
objects except for two which work differently for counters.
-
fromkeys
(
iterable
)
¶
-
此类方法未实现对于
Counter
对象。
-
update
(
[
iterable-or-mapping
]
)
¶
-
元素的计数来自
iterable
or added-in from another
映射
(or counter). Like
dict.update()
but adds counts instead of replacing them. Also, the
iterable
is expected to be a sequence of elements, not a sequence of
(key, value)
pairs.
Counters support rich comparison operators for equality, subset, and superset relationships:
==
,
!=
,
<
,
<=
,
>
,
>=
. All of those tests treat missing elements as having zero counts so that
Counter(a=1) == Counter(a=1, b=0)
返回 True。
3.10 版改变：
Rich comparison operations were added.
3.10 版改变：
In equality tests, missing elements are treated as having zero counts. Formerly,
Counter(a=3)
and
Counter(a=3, b=0)
were considered distinct.
Common patterns for working with
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
Several mathematical operations are provided for combining
Counter
objects to produce multisets (counters that have counts greater than zero). Addition and subtraction combine counters by adding or subtracting the counts of corresponding elements. Intersection and union return the minimum and maximum of corresponding counts. Equality and inclusion compare corresponding counts. Each operation can accept inputs with signed counts, but the output will exclude results with counts of zero or less.
>>> 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
Unary addition and subtraction are shortcuts for adding an empty counter or subtracting from an empty counter.
>>> c = Counter(a=2, b=-4)
>>> +c
Counter({'a': 2})
>>> -c
Counter({'b': 4})
Added in version 3.3:
Added support for unary plus, unary minus, and in-place multiset operations.
注意
Counters were primarily designed to work with positive integers to represent running counts; however, care was taken to not unnecessarily preclude use cases needing other types or negative values. To help with those use cases, this section documents the minimum range and type restrictions.
-
The
Counter
class itself is a dictionary subclass with no restrictions on its keys and values. The values are intended to be numbers representing counts, but you
could
store anything in the value field.
-
The
most_common()
method requires only that the values be orderable.
-
For in-place operations such as
c[key] += 1
, the value type need only support addition and subtraction. So fractions, floats, and decimals would work and negative values are supported. The same is also true for
update()
and
subtract()
which allow negative and zero values for both inputs and outputs.
-
The multiset methods are designed only for use cases with positive values. The inputs may be negative or zero, but only outputs with positive values are created. There are no type restrictions, but the value type needs to support addition, subtraction, and comparison.
-
The
elements()
method requires integer counts. It ignores zero and negative counts.
另请参阅
-
Bag class
in Smalltalk.
-
维基百科条目对于
Multisets
.
-
C++ multisets
tutorial with examples.
-
For mathematical operations on multisets and their use cases, see
Knuth, Donald. The Art of Computer Programming Volume II, Section 4.6.3, Exercise 19
.
-
To enumerate all distinct multisets of a given size over a given set of elements, see
itertools.combinations_with_replacement()
:
map(Counter, combinations_with_replacement('ABC', 2)) # --> AA AB AC BB BC CC
-
class
集合。
deque
(
[
iterable
[
,
maxlen
]
]
)
¶
-
Returns a new deque object initialized left-to-right (using
append()
) with data from
iterable
。若
iterable
is not specified, the new deque is empty.
Deques are a generalization of stacks and queues (the name is pronounced “deck” and is short for “double-ended queue”). Deques support thread-safe, memory efficient appends and pops from either side of the deque with approximately the same
O
(1) performance in either direction.
Though
list
objects support similar operations, they are optimized for fast fixed-length operations and incur
O
(
n
) memory movement costs for
pop(0)
and
insert(0, v)
operations which change both the size and position of the underlying data representation.
若
maxlen
未指定或是
None
, deques may grow to an arbitrary length. Otherwise, the deque is bounded to the specified maximum length. Once a bounded length deque is full, when new items are added, a corresponding number of items are discarded from the opposite end. Bounded length deques provide functionality similar to the
tail
filter in Unix. They are also useful for tracking transactions and other pools of data where only the most recent activity is of interest.
Deque objects support the following methods:
-
append
(
x
)
¶
-
添加
x
to the right side of the deque.
-
appendleft
(
x
)
¶
-
添加
x
to the left side of the deque.
-
clear
(
)
¶
-
Remove all elements from the deque leaving it with length 0.
-
copy
(
)
¶
-
Create a shallow copy of the deque.
Added in version 3.5.
-
count
(
x
)
¶
-
Count the number of deque elements equal to
x
.
Added in version 3.2.
-
extend
(
iterable
)
¶
-
Extend the right side of the deque by appending elements from the iterable argument.
-
extendleft
(
iterable
)
¶
-
Extend the left side of the deque by appending elements from
iterable
. Note, the series of left appends results in reversing the order of elements in the iterable argument.
-
index
(
x
[
,
start
[
,
stop
]
]
)
¶
-
Return the position of
x
in the deque (at or after index
start
and before index
stop
). Returns the first match or raises
ValueError
若找不到。
Added in version 3.5.
-
insert
(
i
,
x
)
¶
-
插入
x
into the deque at position
i
.
If the insertion would cause a bounded deque to grow beyond
maxlen
，
IndexError
被引发。
Added in version 3.5.
-
pop
(
)
¶
-
Remove and return an element from the right side of the deque. If no elements are present, raises an
IndexError
.
-
popleft
(
)
¶
-
Remove and return an element from the left side of the deque. If no elements are present, raises an
IndexError
.
-
remove
(
值
)
¶
-
Remove the first occurrence of
value
. If not found, raises a
ValueError
.
-
reverse
(
)
¶
-
Reverse the elements of the deque in-place and then return
None
.
Added in version 3.2.
-
rotate
(
n
=
1
)
¶
-
Rotate the deque
n
steps to the right. If
n
is negative, rotate to the left.
When the deque is not empty, rotating one step to the right is equivalent to
d.appendleft(d.pop())
, and rotating one step to the left is equivalent to
d.append(d.popleft())
.
Deque objects also provide one read-only attribute:
-
maxlen
¶
-
Maximum size of a deque or
None
若无限。
Added in version 3.1.
In addition to the above, deques support iteration, pickling,
len(d)
,
reversed(d)
,
copy.copy(d)
,
copy.deepcopy(d)
, membership testing with the
in
operator, and subscript references such as
d[0]
to access the first element. Indexed access is
O
(1) at both ends but slows to
O
(
n
) in the middle. For fast random access, use lists instead.
Starting in version 3.5, deques support
__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'])
This section shows various approaches to working with deques.
Bounded length deques provide functionality similar to the
tail
filter in Unix:
def tail(filename, n=10):
'Return the last n lines of a file'
with open(filename) as f:
return deque(f, n)
Another approach to using deques is to maintain a sequence of recently added elements by appending to the right and popping to the left:
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
A
round-robin scheduler
can be implemented with input iterators stored in a
deque
. Values are yielded from the active iterator in position zero. If that iterator is exhausted, it can be removed with
popleft()
; otherwise, it can be cycled back to the end with the
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()
The
rotate()
method provides a way to implement
deque
slicing and deletion. For example, a pure Python implementation of
del d[n]
relies on the
rotate()
method to position elements to be popped:
def delete_nth(d, n):
d.rotate(-n)
d.popleft()
d.rotate(n)
要实现
deque
slicing, use a similar approach applying
rotate()
to bring a target element to the left side of the deque. Remove old entries with
popleft()
, add new entries with
extend()
, and then reverse the rotation. With minor variations on that approach, it is easy to implement Forth style stack manipulations such as
dup
,
drop
,
swap
,
over
,
pick
,
rot
，和
roll
.
-
class
集合。
defaultdict
(
default_factory=None
,
/
[
,
...
]
)
¶
-
返回新的像字典对象。
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__()
is
not
被调用对于任何操作除了
__getitem__()
。这意味着
get()
将像正常字典，返回
None
作为默认而不是使用
default_factory
.
defaultdict
对象支持以下实例变量：
-
default_factory
¶
-
此属性用于
__missing__()
method; it is initialized from the first argument to the constructor, if present, or to
None
, if absent.
3.9 版改变：
添加合并 (
|
) 和更新 (
|=
) 运算符，指定在
PEP 584
.
使用
list
作为
default_factory
, it is easy to group a sequence of key-value pairs into a dictionary of lists:
>>> 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])]
When each key is encountered for the first time, it is not already in the mapping; so an entry is automatically created using the
default_factory
function which returns an empty
list
。
list.append()
operation then attaches the value to the new list. When keys are encountered again, the look-up proceeds normally (returning the list for that key) and the
list.append()
operation adds another value to the list. This technique is simpler and faster than an equivalent technique using
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
to
int
makes the
defaultdict
useful for counting (like a bag or multiset in other languages):
>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
... d[k] += 1
...
>>> sorted(d.items())
[('i', 4), ('m', 1), ('p', 2), ('s', 4)]
When a letter is first encountered, it is missing from the mapping, so the
default_factory
函数调用
int()
to supply a default count of zero. The increment operation then builds up the count for each letter.
函数
int()
which always returns zero is just a special case of constant functions. A faster and more flexible way to create constant functions is to use a lambda function which can supply any constant value (not just zero):
>>> 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
to
set
makes the
defaultdict
useful for building a dictionary of sets:
>>> 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
(
typename
,
field_names
,
*
,
rename
=
False
,
defaults
=
None
,
模块
=
None
)
¶
-
返回新的元组子类命名
typename
。使用新子类创建拥有通过属性查找可访问 (还可索引、可迭代) 字段的像元组对象。子类实例还拥有有用 docstring 文档字符串 (具有 typename 和 field_names) 和有用
__repr__()
方法列出元组内容按
name=value
格式。
The
field_names
是字符串序列譬如
['x', 'y']
。另外，
field_names
可以是每个字段名由空格和/或逗号分隔的单字符串，例如
'x y'
or
'x, y'
.
任何有效 Python 标识符都可以用作字段名，但以下划线开头的名称除外。有效标识符由字母、数字及下划线组成，但不能以数字 (或下划线) 开头，且不可以是
keyword
譬如
class
,
for
,
return
,
global
,
pass
，或
raise
.
若
rename
为 True，无效字段名称会被自动替换为位置名称。例如，
['abc', 'def', 'ghi', 'abc']
被转换成
['abc', '_1', 'ghi', '_3']
，消除关键词
def
和重复字段名
abc
.
defaults
可以是
None
或
iterable
作默认值。由于具有默认值的字段必须在没有默认值的任何字段之后，
defaults
被应用到最右边参数。例如，若字段名为
['x', 'y', 'z']
和 defaults 为
(1, 2)
，那么
x
将是要求自变量，
y
将默认为
1
，和
z
将默认为
2
.
若
模块
有定义，
__module__
属性在命名元组被设为该值。
命名元组实例没有每实例字典，因此它们很轻量，且不要求更多内存相比常规元组。
为支持腌制，应将命名元组类赋值给变量以匹配
typename
.
3.1 版改变：
添加支持
rename
.
3.6 版改变：
The
verbose
and
rename
参数变为
仅关键词自变量
.
3.6 版改变：
添加
模块
参数。
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
or
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)
从元组继承的方法除外，命名元组还支持 3 方法和 2 属性。为防止与字段名冲突，方法和属性名以下划线开头。
-
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())
Named tuples are also supported by generic function
copy.replace()
.
Changed in version 3.13:
引发
TypeError
而不是
ValueError
for invalid keyword arguments.
-
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()
函数：
要将字典转换成命名元组，请使用双星运算符 (作为描述在
解包自变量列表
):
>>> 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',))
可以定制 docstring (文档字符串) 通过直接赋值给
__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 版改变：
特性 docstring (文档字符串) 变为可写。
另请参阅
-
见
typing.NamedTuple
for a way to add type hints for named tuples. It also provides an elegant notation using the
class
关键词：
class Component(NamedTuple):
part_number: int
weight: float
description: Optional[str] = None
见
types.SimpleNamespace()
for a mutable namespace based on an underlying dictionary instead of a tuple.
The
dataclasses
module provides a decorator and functions for automatically adding generated special methods to user-defined classes.
有序字典就像普通字典，但拥有一些排序操作相关的额外能力。现在它们变得不太重要了，内置
dict
类获得了记住插入次序的能力 (这种新行为在 Python 3.7 获得保证)。
一些差异同
dict
仍然保留：
-
常规
dict
被设计成非常擅长映射操作。追踪插入次序是次要的。
-
The
OrderedDict
被设计成很擅长重新排序操作。空间效率、迭代速度及更新操作的性能，是次要的。
-
The
OrderedDict
algorithm can handle frequent reordering operations better than
dict
. As shown in the recipes below, this makes it suitable for implementing various kinds of LRU caches.
-
相等运算对于
OrderedDict
会校验匹配次序。
常规
dict
can emulate the order sensitive equality test with
p == q and all(k1 == k2 for k1, k2 in zip(p, q))
.
-
The
popitem()
方法为
OrderedDict
有不同的签名。它接受可选自变量以指定弹出哪项。
常规
dict
可以模拟 OrderedDict 的
od.popitem(last=True)
with
d.popitem()
which is guaranteed to pop the rightmost (last) item.
常规
dict
可以模拟 OrderedDict 的
od.popitem(last=False)
with
(k := next(iter(d)), d.pop(k))
which will return and remove the leftmost (first) item if it exists.
-
OrderedDict
拥有
move_to_end()
方法以高效将元素重新定位到端点。
常规
dict
可以模拟 OrderedDict 的
od.move_to_end(k,
last=True)
with
d[k] = d.pop(k)
which will move the key and its associated value to the rightmost (last) position.
常规
dict
does not have an efficient equivalent for OrderedDict’s
od.move_to_end(k, last=False)
which moves the key and its associated value to the leftmost (first) position.
-
直到 Python 3.8，
dict
缺乏
__reversed__()
方法。
-
class
集合。
OrderedDict
(
[
items
]
)
¶
-
返回实例化的
dict
子类拥有专用于重新排列字典次序的方法。
Added in version 3.1.
-
popitem
(
last
=
True
)
¶
-
The
popitem()
方法返回并移除有序词典 (键，值) 对。对被返回按
LIFO
次序若
last
为 True 或
FIFO
次序若 False。
-
move_to_end
(
key
,
last
=
True
)
¶
-
移动现有
key
到有序字典的任一端。将项移至右端若
last
为 True (默认)，或到开始若
last
为 False。引发
KeyError
若
key
不存在：
>>> d = OrderedDict.fromkeys('abcde')
>>> d.move_to_end('b')
>>> ''.join(d)
'acdeb'
>>> d.move_to_end('b', last=False)
>>> ''.join(d)
'bacde'
Added in version 3.2.
除通常映射方法外，有序词典还支持反向迭代使用
reversed()
.
相等性测试在
OrderedDict
objects are order-sensitive and are roughly equivalent to
list(od1.items())==list(od2.items())
.
相等性测试在
OrderedDict
对象和其它
Mapping
对象像常规字典是次序不敏感的。这允许
OrderedDict
对象要在任何地方使用常规字典被代入。
3.5 版改变：
items、keys 和 values
views
of
OrderedDict
现在支持反向迭代使用
reversed()
.
3.6 版改变：
随着接受
PEP 468
，关键词自变量次序被保留并被传递给
OrderedDict
构造函数及其
update()
方法。
3.9 版改变：
添加合并 (
|
) 和更新 (
|=
) 运算符，指定在
PEP 584
.
It is straightforward to create an ordered dictionary variant that remembers the order the keys were
last
inserted. If a new entry overwrites an existing entry, the original insertion position is changed and moved to the end:
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)
An
OrderedDict
would also be useful for implementing variants of
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
acts as a wrapper around dictionary objects. The need for this class has been partially supplanted by the ability to subclass directly from
dict
; however, this class can be easier to work with because the underlying dictionary is accessible as an attribute.
-
class
集合。
UserDict
(
[
initialdata
]
)
¶
-
Class that simulates a dictionary. The instance’s contents are kept in a regular dictionary, which is accessible via the
data
attribute of
UserDict
实例。若
initialdata
is provided,
data
is initialized with its contents; note that a reference to
initialdata
will not be kept, allowing it to be used for other purposes.
In addition to supporting the methods and operations of mappings,
UserDict
instances provide the following attribute:
-
data
¶
-
A real dictionary used to store the contents of the
UserDict
类。
This class acts as a wrapper around list objects. It is a useful base class for your own list-like classes which can inherit from them and override existing methods or add new ones. In this way, one can add new behaviors to lists.
The need for this class has been partially supplanted by the ability to subclass directly from
list
; however, this class can be easier to work with because the underlying list is accessible as an attribute.
-
class
集合。
UserList
(
[
list
]
)
¶
-
Class that simulates a list. The instance’s contents are kept in a regular list, which is accessible via the
data
attribute of
UserList
instances. The instance’s contents are initially set to a copy of
list
, defaulting to the empty list
[]
.
list
can be any iterable, for example a real Python list or a
UserList
对象。
In addition to supporting the methods and operations of mutable sequences,
UserList
instances provide the following attribute:
-
data
¶
-
真实
list
对象用于存储内容为
UserList
类。
子类化要求：
子类化的
UserList
are expected to offer a constructor which can be called with either no arguments or one argument. List operations which return a new sequence attempt to create an instance of the actual implementation class. To do so, it assumes that the constructor can be called with a single parameter, which is a sequence object used as a data source.
If a derived class does not wish to comply with this requirement, all of the special methods supported by this class will need to be overridden; please consult the sources for information about the methods which need to be provided in that case.
类
UserString
acts as a wrapper around string objects. The need for this class has been partially supplanted by the ability to subclass directly from
str
; however, this class can be easier to work with because the underlying string is accessible as an attribute.
-
class
集合。
UserString
(
seq
)
¶
-
Class that simulates a string object. The instance’s content is kept in a regular string object, which is accessible via the
data
attribute of
UserString
instances. The instance’s contents are initially set to a copy of
seq
。
seq
argument can be any object which can be converted into a string using the built-in
str()
函数。
In addition to supporting the methods and operations of strings,
UserString
instances provide the following attribute:
-
data
¶
-
真实
str
对象用于存储内容为
UserString
类。
3.5 版改变：
New methods
__getnewargs__
,
__rmod__
,
casefold
,
format_map
,
isprintable
，和
maketrans
.
