pyjq: jq JSON处理器绑定

pyjq是jq（《http://stedolan.github.io/jq/》）的Python绑定。

jq类似于用于JSON数据的sed - 您可以使用它以与sed、awk、grep等处理文本相同的方式轻松切片、筛选、映射和转换结构化数据。

http://stedolan.github.io/jq/

您可以无缝调用jq脚本（如正则表达式）并处理原始Python数据结构。

请注意，https://pypi.python.org/pypi/jq是另一个与pyjq不同且不兼容的jq绑定。

示例

>>> data = dict(
...     parameters= [
...         dict(name="PKG_TAG_NAME", value="trunk"),
...         dict(name="GIT_COMMIT", value="master"),
...         dict(name="TRIGGERED_JOB", value="trunk-buildall")
...     ],
...     id="2013-12-27_00-09-37",
...     changeSet=dict(items=[], kind="git"),
... )
>>> import pyjq
>>> pyjq.first('.parameters[] | {"param_name": .name, "param_type":.type}', data)
{'param_name': 'PKG_TAG_NAME', 'param_type': None}

安装

您需要flex、bison（3.0或更高版本）、libtool、make、automake和autoconf来构建jq。您可以通过Homebrew、APT或其他方式安装它们。

您可以通过常规方式从PyPI安装。

pip install pyjq

API

有关jq脚本，请参阅其《手册》。

仅提供四个API

• all
• first
• one
• compile

all通过JSON脚本转换值并返回所有结果作为列表。

>>> value = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
>>> pyjq.all('{user, title: .titles[]}', value)
[{'user': 'stedolan', 'title': 'JQ Primer'}, {'user': 'stedolan', 'title': 'More JQ'}]

all接受一个可选的vars参数。vars是预定义变量字典，用于script。在vars中的值在script中作为$key可用。也就是说，vars的作用类似于jq命令的--arg选项和--argjson选项。

>>> pyjq.all('{user, title: .titles[]} | select(.title == $title)', value, vars={"title": "More JQ"})
[{'user': 'stedolan', 'title': 'More JQ'}]

all接受一个可选的url参数。如果提供了url，则从url检索转换的主题。

>> pyjq.all(".[] | .login", url="https://api.github.com/repos/stedolan/jq/contributors") # get all contributors of jq
['nicowilliams', 'stedolan', 'dtolnay', ... ]

此外，all 函数接受一个可选的参数 opener。默认的 opener 会使用 urllib.request.urlopen 下载内容，并使用 json.decode 解码。然而，您可以使用自定义的 opener 来自定义此行为。

first 和 one 函数与 all 类似。

first 函数返回转换的第一个结果。如果没有结果，first 函数返回 None 或指定的 default 值。

>>> data = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
>>> pyjq.first('{user, title: .titles[]}', data)
{'user': 'stedolan', 'title': 'JQ Primer'}
>>> pyjq.first('.titles[] | select(test("T"))', data) # returns None
>>> pyjq.first('.titles[] | select(test("T"))', data, default="Third JS")
'Third JS'

one 函数返回转换的唯一结果。如果没有结果或者有两个或更多结果时，它将抛出一个异常。

>>> data = {"user":"stedolan","titles": ["JQ Primer", "More JQ"]}
>>> pyjq.one('.titles[] | select(test("P"))', data)
'JQ Primer'
>>> pyjq.one('.titles[] | select(test("T"))', data)
Traceback (most recent call last):
IndexError: Result of jq is empty
>>> pyjq.one('.titles[] | select(test("J"))', data)
Traceback (most recent call last):
IndexError: Result of jq have multiple elements

compile 函数类似于 re.compile。它接受 jq 脚本并返回一个包含方法的对象。

>>> data = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
>>> import pyjq
>>> pat = pyjq.compile('{user, title: .titles[]}')
>>> pat.all(data)
[{'user': 'stedolan', 'title': 'JQ Primer'}, {'user': 'stedolan', 'title': 'More JQ'}]

限制

jq 是一个 JSON 处理器。因此，pyjq 只能处理“JSON 兼容”的数据（仅由 str、int、float、list、dict 组成的对象）。

问答

如何使用 pyjq 处理 JSON 字符串（例如从 API 获取的）？

在将字符串传递给 pyjq 之前，您应该使用标准库中的 json.loads 调用该字符串。

作者

OMOTO Kenji

许可证

MIT 许可证。请参阅 LICENSE。

此包包含 jq 和 oniguruma。它们的许可文件包含在其各自的存档文件中。

• jq: dependencies/jq-1.5.tar.gz
• oniguruma: dependencies/onig-6.9.0.tar.gz

变更日志

2.6.0

• 支持 3.10

2.5.1

• 修复了拼写错误。

2.5.0

• 只支持 3.7+。
• 添加了 pyjq.ScriptRuntimeError。

2.4.0

• 停止支持 Python 2.7、3.4、3.5（只支持 3.6+）。

2.3.0

• 支持 WindowsPE(msys)

2.2.0

• 添加了 library_paths= 选项。

2.1.0

• API 的 translate JS 对象不再转换为 dict，而是转换为 collections.OrderedDict。

2.0.0

• 语义版本控制。
• 打包 jq 和 oniguruma 的源代码。
• 支持 Python 3.5。
• 停止支持 Python 3.2。
• 添加了 all 方法。

1.0

• 第一个版本。