deep-collections 0.4.2

Deep Collections

deep_collections是一个Python库，它提供了一种工具，可以轻松访问深层集合（字典、列表、双端队列等），同时保留大部分集合的原始API。DeepCollection类将自动子类化提供的原始集合，并添加一些提高生活质量的扩展，使得使用深层集合变得更加愉快。

从API获取了一堆JSON？来自某个数据科学问题的庞大Python对象？来自Ansible或SaltStack等基础设施即代码的一些非常长的指令集？轻松探索和修改它们。

DeepCollection可以接受几乎所有类型的对象，包括所有内置容器类型（字典、列表、集合、元组）、collections模块中的所有内容以及dotty-dicts，以及所有这些都可以以任何方式嵌套。

功能

• 通过提供一组路径组件作为键进行路径遍历。这适用于获取、设置和删除。
• 仅通过路径片段访问嵌套组件。
• 在父组件不存在时设置路径。
• 通过点连接字典样式的集合进行路径遍历以获取
• 找到所有键或子路径的路径
• 找到所有键或子路径的值，并去重。
• 通过一个易于实例化的类提供上述所有功能
  • 易于实例化
  • 是其实例化类型的本地子类
  • 易于子类化

路径概念

DeepCollections 有一个嵌套集合的“路径”概念，其中路径是一系列键或索引的序列，如果按顺序遍历，则遍历深层集合。例如，{'a': ['b', {'c': 'd'}]}可以使用路径['a', 1, 'c']遍历以找到值'd'。

DeepCollections 本地使用路径以及简单的键和索引。对于dc = DeepCollection(foo)，如果path是简单的键或索引，或者它是一个非字符串类型的可迭代路径（字符串被认为是字面键），则可以通过熟悉的dc[path]进行检索。这是通过自定义的__getitem__方法实现的。同样，__delitem__和__setitem__也支持使用路径。对于熟悉的像.get这样的方法也存在相同的灵活性，它的行为与dict.get相同，但也可以接受路径以及键。

匹配

路径元素被解释为与键和索引匹配的模式。默认情况下，此功能是开启的，并使用globbing。

递归

"**"递归任何深度以找到下一个模式的匹配项。例如

dc = DeepCollection({"a": {"b": {"c": {"d": 5}}}, "d": 4})
dc["a", "**", "d"] == 5

结合另一种匹配风格，如globbing，可以进行一些强大的过滤

dc = DeepCollection({"a": {"b": {"c": {"xd": {"e": 0}, "yd": {"e": 1}, "zf": {"e": 2}}}}, "e": 3})
dc["a", "**", "?d", "e"] == [0, 1]

此功能独立于其他匹配模式。换句话说，您可以将globbing替换为另一种匹配风格，但"**"将保持可用性，除非单独禁用它。您可能希望通过路径使用regex，但与递归搭配使用。

匹配数字键和索引

为了在尝试匹配索引和数字键时使模式匹配有意义，如果路径元素是字符串并且看起来使用了globbing，它将与字符串化的索引/键进行匹配。换句话说

dc = DeepCollection(["a", "b", "c"])
dc["[0-1]"] == DeepCollection(["a", "b"])
dc["[5]"] == DeepCollection([])  # Matching pattern detected (globbing), so no results yields an empty list.
dc["5"]  # Raises TypeError. No matching pattern detected, so direct use of `"5"` was attempted and not cast to an int.

dc = DeepCollection({1: 'i', '1': 'j', 'a': 'k'})
dc['*[!1]'] == "k"

这是为了使模式匹配索引和数字键的一种折衷方案。与更深层次的路径遍历一样，由于我们正在匹配一个模式，所以0次命中不会被处理为KeyError或IndexError，而只是返回一个空列表。

当未检测到模式匹配时，都会保留通常依赖于的KeyError和IndexError。

dc = DeepCollection(["a", "b", "c"])
dc[5]
...
IndexError: list index out of range

DeepCollection({})["a"]
...
KeyError: 'a'

匹配风格

Deep Collections 支持以下匹配风格

• glob
• regex
• 相等
• hash
• glob+regex
• 自定义（即将内置）

这可以通过许多函数设置，例如通过传递match_with="regex"。

如上所述，特殊使用"**"是独立的，并且目前始终开启。未来的版本将允许切换此选项。

为了放弃所有匹配风格并尽可能快速地遍历路径，请使用getitem_by_path_strict。

匹配风格：Globbing

任何给定的路径元素都与Python stdlib中的fnmatchcase进行匹配。此风格用于上述示例。

匹配风格：Regex

任何给定的路径元素都与Python stdlib中的re.compile().match()进行匹配。

DeepCollection对象API

DeepCollections作为正常类实例化，可选地以给定初始集合作为参数。

from deep_collections import DeepCollection

dc = DeepCollection()
# or
dc = DeepCollection({"a": {"b": {"c": "d"}}})
# or
dc = DeepCollection(["a", ["b", ["c", "d"]]])

以下是在所有DCs上可用的值得注意的方法

• __getitem__
• __delitem__
• __setitem__
• get
• paths_to_value
• paths_to_key
• values_for_key
• deduped_values_for_key

同时也有相应的函数可用，可以使用任何可能是深层但不是DeepCollection的原生对象，比如普通的嵌套dict或list。这可能是遍历你已经拥有的对象的便捷替代方案，但使用它也更快，因为它不需要DeepCollection对象的初始化成本。所以如果速度很重要，请使用函数。

deep_collections函数API

DeepCollection对象的所有有用方法都作为可以接受集合作为参数的函数提供，以及一些其他支持函数，这些函数被明显地提供。

核心函数集中于使用相同的路径概念。可用的函数及其相关的DC方法包括

• getitem_by_path - DeepCollection().__getitem__
• get_by_path - DeepCollection().get
• set_by_path - DeepCollection().set_by_path
• del_by_path - DeepCollection().del_by_path
• paths_to_value - DeepCollection().paths_to_value
• paths_to_key - DeepCollection().paths_to_key
• values_for_key - DeepCollection().values_for_key
• deduped_values_for_key - DeepCollection().deduped_values_for_key
• dedupe_items
• resolve_path
• matched_keys