dictutils -映射类型(OMD)

Python的核心有一个非常强大的映射类型： dict 键入。虽然功能齐全，但 dict 优先考虑简单性和性能。因此，它不会保留项目插入的顺序 [1], 它也不会为每个键存储多个值。这是一种快速、无序的1：1映射。

这个 OrderedMultiDict 与内置的 dict ，作为一个相对最大的，排序的1：N亚型 dict 。几乎所有的功能 dict 在面对这种增加的复杂性时，已经进行了重新调整，使其变得直观。添加了其他方法，例如 collections.Counter -类似功能。

最大的优势是 OrderedMultiDict (OMD)是它的非破坏性。可以将数据添加到 OMD 不会被重新排列或重写。该属性允许开发人员更自由地使用数据，并对输入数据在输出中的结束位置做出更多假设，所有这些都不需要任何额外工作。

这方面的一个很好的例子是 OMD.inverted() 方法，该方法返回一个新的OMD，其中值是键，键是值。所有数据和相应的顺序仍然以倒置的形式表示，所有这些都来自于使用内置的 dict 或 collections.OrderedDict 。

OMD的性能已经过调整，适合于广泛的用途，包括作为基本的无序多用途。特别感谢 Mark Williams 感谢他的所有帮助。

[1]

截至2015年， basic dicts on PyPy are ordered ，截至2017年12月， basic dicts in CPython 3 are now ordered 也是如此。

class boltons.dictutils.FrozenDict

一个不可变的dict子类型，它是可哈希的，并且本身可以用作 dict 键或 set 进入。什么 frozenset 是为了 set ，FrozenDict是要 dict 。

曾经有人试图将这种类型引入标准库，但遭到拒绝： PEP 416 。

因为《冰雪奇缘》是一个 dict 子类型，它会自动在DICT的任何地方工作，包括JSON序列化。

clear(*a, **kw)

引发TypeError，因为FrozenDicts是不可变的

classmethod fromkeys(keys, value=None)

创建一个新字典，其关键字来自可迭代，值设置为Value。

pop(*a, **kw)

引发TypeError，因为FrozenDicts是不可变的

popitem(*a, **kw)

引发TypeError，因为FrozenDicts是不可变的

setdefault(*a, **kw)

引发TypeError，因为FrozenDicts是不可变的

update(*a, **kw)

引发TypeError，因为FrozenDicts是不可变的

updated(*a, **kw)

复制并添加字典或可迭代(和/或关键字参数)中的项，覆盖现有键下的值。看见 dict.update() 了解更多详细信息。

class boltons.dictutils.ManyToMany(items=None)

表示两组对象之间的多对多关系的类词典实体

行为类似于元组字典；还有保持最新的.inv，这是另一个方向的元组字典

此外，还可以用作可哈希的Python对象之间的有向图

add(key, val)

get(key, default=frozenset({}))

iteritems()

keys()

remove(key, val)

replace(key, newkey)

用NewKey替换Key的实例

update(iterable)

给定一个可迭代的(key，val)，将它们全部相加

boltons.dictutils.MultiDict

OrderedMultiDict 的别名

boltons.dictutils.OMD

OrderedMultiDict 的别名

class boltons.dictutils.OneToOne(*a, **kw)

实现一对一映射词典。除了继承和表现与建筑一模一样 dict ，所有值都自动添加为反向映射上的键，该反向映射可作为 inv 属性。这种安排使键和值命名空间保持不同。

基本操作非常直观：

>>> oto = OneToOne({'a': 1, 'b': 2})
>>> print(oto['a'])
1
>>> print(oto.inv[1])
a
>>> len(oto)
2

覆盖发生在两个方向上：

>>> oto.inv[1] = 'c'
>>> print(oto.get('a'))
None
>>> len(oto)
2

对于一个非常类似的项目，具有更多的一对一功能，请查看 bidict 。

clear() → None.  Remove all items from D.

copy() → a shallow copy of D

inv

pop(k[, d]) → v, remove specified key and return the corresponding value.

如果找不到键，则返回默认值(如果给定)；否则，引发KeyError。

popitem()

移除(键、值)对并将其作为二元组返回。

对按后进先出(LIFO)顺序返回。如果判定为空，则引发KeyError。

setdefault(key, default=None)

如果Key不在词典中，则插入值为Default的Key。

如果key在字典中，则返回key的值，否则返回Default。

classmethod unique(*a, **kw)

当输入值重叠时，ONEtoONE的这个备用构造函数将引发异常。例如：

>>> OneToOne.unique({'a': 1, 'b': 1})
Traceback (most recent call last):
...
ValueError: expected unique values, got multiple keys for the following values: ...

这甚至适用于所有输入：

>>> a_dict = {'a': 2}
>>> OneToOne.unique(a_dict, b=2)
Traceback (most recent call last):
...
ValueError: expected unique values, got multiple keys for the following values: ...

update([E, ]**F) → None.  Update D from dict/iterable E and F.

如果E存在并且具有.key()方法，则会这样做：for k in E：D [k] =E [k] 如果E存在并且缺少.key()方法，则会这样做：对于k，E：D中的v [k] =v在任何一种情况下，后跟：表示F：D中的k [k] =F [k]

class boltons.dictutils.OrderedMultiDict(*a, **kw)

多指令集是每个键可以有多个值的字典，而有序多指令集(OMD)是保留原始插入顺序的多指令集。常见使用案例包括：

• 处理从URL解析的查询字符串

• 倒排词典以创建倒排索引(键的值)

• 以非破坏性的方式堆叠来自多个词典的数据

OrderedMultiDict构造函数与内置的 dict ，总的来说，该API构成了内置类型的直观超集：

>>> omd = OrderedMultiDict()
>>> omd['a'] = 1
>>> omd['b'] = 2
>>> omd.add('a', 3)
>>> omd.get('a')
3
>>> omd.getlist('a')
[1, 3]

一些非 -dict -类似的行为也会出现，例如支持 reversed() ：

>>> list(reversed(omd))
['b', 'a']

请注意，与其他一些MultiDicts不同，此OMD优先考虑最近增加的价值。 omd['a'] 指 3 ，不 1 。

>>> omd
OrderedMultiDict([('a', 1), ('b', 2), ('a', 3)])
>>> omd.poplast('a')
3
>>> omd
OrderedMultiDict([('a', 1), ('b', 2)])
>>> omd.pop('a')
1
>>> omd
OrderedMultiDict([('b', 2)])

如果您想要安全修改或平面词典，请使用 OrderedMultiDict.todict() 。

>>> from pprint import pprint as pp  # preserve printed ordering
>>> omd = OrderedMultiDict([('a', 1), ('b', 2), ('a', 3)])
>>> pp(omd.todict())
{'a': 3, 'b': 2}
>>> pp(omd.todict(multi=True))
{'a': [1, 3], 'b': [2]}

使用 multi=False 时，项将以原始插入顺序显示，旁边是该键的最近插入的值。

>>> OrderedMultiDict([('a', 1), ('b', 2), ('a', 3)]).items(multi=False)
[('a', 3), ('b', 2)]

警告

dict(omd) 改变的行为 in Python 3.7 由于为支持从 collections.OrderedDict 到正在订购的内置词典。在3.7之前，结果将是一个新的字典，其中的值是列表，类似于 omd.todict(multi=True) (但只是浅层复制；这些列表是对OMD内部结构的直接引用)。从3.7开始，值变得单一，如下所示 omd.todict(multi=False) 。要获得可靠的跨版本行为，只需使用 todict() 。

add(k, v)

添加单个值 v 在钥匙下 k 。项下的现有值 k 都保存了下来。

addlist(k, v)

在特定键下添加一个可迭代值，保留该键下已有的任何值。

>>> omd = OrderedMultiDict([('a', -1)])
>>> omd.addlist('a', range(3))
>>> omd
OrderedMultiDict([('a', -1), ('a', 0), ('a', 1), ('a', 2)])

被呼叫 addlist 为了保持与 getlist() ，但是元组和其他序列和迭代器可以工作。

clear()

清空字典。

copy()

退还这本词典的浅本。

counts()

返回从键到该键下插入的值数的映射。喜欢 collections.Counter ，但返回一个新的 OrderedMultiDict 。

classmethod fromkeys(keys, default=None)

从键列表创建字典，并将所有值设置为 default ，或 None 如果 default 未设置。

get(k, default=None)

返回key的值 k 如果出现在词典中，则为 default 。如果 default 不是被给予的， None 是返回的。此方法永远不会引发 KeyError 。

要获取一个键下的所有值，请使用 OrderedMultiDict.getlist() 。

getlist(k, default=_MISSING)

获取键的所有值 k 作为列表，如果 k 在词典中，否则 default 。返回的列表是副本，可以安全地更改。如果 default 不是给的，就是空的 list 是返回的。

inverted()

返回一个新的 OrderedMultiDict 值和键互换，比如创建词典转置或倒排索引。插入顺序保持不变，所有键和值都显示在输出中。

>>> omd = OMD([(0, 2), (1, 2)])
>>> omd.inverted().getlist(2)
[0, 1]

反转两次会生成原始文件的副本：

>>> omd.inverted().inverted()
OrderedMultiDict([(0, 2), (1, 2)])

items(multi=False)

返回一个列表，该列表包含 iteritems() 。有关更多详细信息，请参阅该方法的文档。

iteritems(multi=False)

按插入顺序迭代OMD的项。默认情况下，只为每个键生成最近插入的值。集 multi 至 True 以获取所有插入的项。

iterkeys(multi=False)

按插入顺序迭代OMD的键。默认情况下，根据最近插入的内容，生成每个密钥一次。集 multi 至 True 以按插入顺序获取所有键，包括重复项。

itervalues(multi=False)

按插入顺序迭代OMD的值。默认情况下，为每个唯一键生成最近插入的值。集 multi 至 True 根据插入顺序获取所有值。

keys(multi=False)

返回一个列表，该列表包含 iterkeys() 。有关更多详细信息，请参阅该方法的文档。

pop(k, default=_MISSING)

删除关键点下的所有值 k ，返回最近插入的值。加薪 KeyError 如果密钥不存在并且没有 default 是提供的。

popall(k, default=_MISSING)

删除关键点下的所有值 k ，以列表的形式返回它们。加薪 KeyError 如果密钥不存在并且没有 default 是提供的。

poplast(k=_MISSING, default=_MISSING)

移除并返回键下最近插入的值 k ，或最近插入的密钥(如果 k 不提供。如果没有任何值保留在 k ，它将从OMD中删除。加薪 KeyError 如果 k 不在词典中，或者词典为空。

setdefault(k, default=_MISSING)

IF密钥 k 在字典中，则返回它的值。如果不是，则插入 k 值为 default 然后回来 default 。 default 默认为 None 。看见 dict.setdefault() 以获取更多信息。

sorted(key=None, reverse=False)

类似于内置的 sorted() ，除非此方法返回一个新的 OrderedMultiDict 按所提供的按键功能排序，可选择颠倒。

参数:

• key (callable) -- 可调用以确定每个元素的排序关键字。可调用对象应期待一个 item (键-值对元组)。

• reverse (bool) -- 设为 True 来颠倒顺序。

>>> omd = OrderedMultiDict(zip(range(3), range(3)))
>>> omd.sorted(reverse=True)
OrderedMultiDict([(2, 2), (1, 1), (0, 0)])

请注意，键函数接收一个 item (键-值元组)，所以推荐的签名如下：

>>> omd = OrderedMultiDict(zip('hello', 'world'))
>>> omd.sorted(key=lambda i: i[1])  # i[0] is the key, i[1] is the val
OrderedMultiDict([('o', 'd'), ('l', 'l'), ('e', 'o'), ('l', 'r'), ('h', 'w')])

sortedvalues(key=None, reverse=False)

返回 OrderedMultiDict 具有与原始OMD相同顺序的相同键，但每个键空间内的值已根据 key 和 reverse 。

参数:

• key (callable) -- 可调用以确定每个元素的排序关键字的单参数。可调用对象应期待一个 item (键-值对元组)。

• reverse (bool) -- 设为 True 来颠倒顺序。

>>> omd = OrderedMultiDict()
>>> omd.addlist('even', [6, 2])
>>> omd.addlist('odd', [1, 5])
>>> omd.add('even', 4)
>>> omd.add('odd', 3)
>>> somd = omd.sortedvalues()
>>> somd.getlist('even')
[2, 4, 6]
>>> somd.keys(multi=True) == omd.keys(multi=True)
True
>>> omd == somd
False
>>> somd
OrderedMultiDict([('even', 2), ('even', 4), ('odd', 1), ('odd', 3), ('even', 6), ('odd', 5)])

如上所述，内容和密钥顺序被保留。只有值顺序更改。

todict(multi=False)

获取一个基本的 dict 这本词典里的词条。键与OMD相同，值是每个键最近插入的值。

设置 multi Arg到 True IS产生的结果与调用 dict 在OMD上，只是所有值列表都是可以安全更改的副本。

update(E, **F)

从字典或可迭代(和/或关键字参数)添加项，覆盖现有键下的值。看见 dict.update() 了解更多详细信息。

update_extend(E, **F)

从字典、可迭代和/或关键字参数添加项，而不覆盖字典中存在的现有项。喜欢 update() ，但会添加到现有密钥中，而不是覆盖它们。

values(multi=False)

返回一个列表，该列表包含 itervalues() 。有关更多详细信息，请参阅该方法的文档。

viewitems() → a set-like object providing a view on OMD's items

viewkeys() → a set-like object providing a view on OMD's keys

viewvalues() → an object providing a view on OMD's values

boltons.dictutils.subdict(d, keep=None, drop=None)

计算词典的“子词典”， d 。

字幕之于词典就像子集之于集合。如果 A 是一种取代 B ，这意味着所有的密钥 A 都存在于 B 。

返回包含任何键的新词典 drop 已移除，并在 keep 仍然存在，前提是它们在原始词典中。 keep 默认为所有键， drop 缺省值为空，因此如果没有这些参数之一，调用此函数等效于调用 dict() 。

>>> from pprint import pprint as pp
>>> pp(subdict({'a': 1, 'b': 2}))
{'a': 1, 'b': 2}
>>> subdict({'a': 1, 'b': 2, 'c': 3}, drop=['b', 'c'])
{'a': 1}
>>> pp(subdict({'a': 1, 'b': 2, 'c': 3}, keep=['a', 'c']))
{'a': 1, 'c': 3}