jpq 0.1.3

jq-style JSON filtering with Python expressions.

jpq

jq-style JSON filtering, but with Python expressions.

The parsed stdin JSON is bound to this; the value of the expression is printed as JSON.

Install

From PyPI:

uv tool install jpq
# or: pipx install jpq
# or: pip install --user jpq

From source, after cloning:

uv tool install .

Or run straight from the checkout without (re)installing:

$ echo '[1, 2]' | uv run main.py 'this[0]'
1

Usage

$ echo '{"name":"alice","age":30}' | jpq 'this["name"]'
"alice"

$ echo '[1,2,3,4,5]' | jpq 'statistics.mean(this)'
3

$ echo '[{"k":"a"},{"k":"b"},{"k":"a"}]' | jpq 'collections.Counter(el["k"] for el in this)'
{"a": 2, "b": 1}

Pre-imported in the eval namespace: re, collections, itertools, statistics, math, datetime, plus all builtins.

Run jpq --help for more.

Advanced examples

Pipe an API response through a multi-line expression to reshape it:

$ curl -s https://api.github.com/repos/python/cpython | jpq '
{
"stars": this["stargazers_count"],
"last_pushed_seconds_ago": (
    datetime.datetime.now(tz=datetime.UTC)
    - datetime.datetime.fromisoformat(this["pushed_at"])
).total_seconds()
}'
{"stars": 72644, "last_pushed_seconds_ago": 2168.664175}

Read environment variables:

export PASS=secret123
echo '{"url": "postgres://user:pass@host:port/db"}' | jpq 'this["url"].replace("pass", env("PASS"))'
# "postgres://user:secret123@host:port/db"

Here env("PASS") is equivalent to os.environ["PASS"] (see helpers.py).