pyjq is a Python binding for the `jq` command-line JSON processor. It allows executing `jq` queries against Python dictionaries and lists, providing flexible and powerful JSON data manipulation capabilities. As of version 2.6.0, it primarily offers a `jq()` function with options for single or multiple results, as well as a `run()` function for CLI-like behavior. It is actively maintained with regular updates.
pip install pyjqVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to use `pyjq.jq()` to query Python dictionaries, including how to handle multiple results with `all_results=True`. It also shows `pyjq.run()` for processing raw JSON string inputs, mimicking the `jq` CLI.
Ensure `jq` is installed on your operating system (e.g., `sudo apt-get install jq` on Debian/Ubuntu, `brew install jq` on macOS, `choco install jq` on Windows) and accessible in your system's PATH before using `pyjq`.
Use the `pyjq.jq()` function directly with the `all_results=True` or `first_result=True` parameters. For example, replace `pyjq.all(query, data)` with `pyjq.jq(query, data, all_results=True)` and `pyjq.first(query, data)` with `pyjq.jq(query, data, first_result=True)` or `next(pyjq.jq(query, data))`.
To get all results as a list, convert the iterator: `list(pyjq.jq(query, data))`, or pass `all_results=True` to the `jq()` function: `pyjq.jq(query, data, all_results=True)`. If you expect a single result, use `next()`: `next(pyjq.jq(query, data))`.
Always ensure your input data is JSON-serializable (dict, list, str, int, bool, None). Validate `jq` query syntax, perhaps using the `jq` CLI first. Wrap `pyjq` calls in `try...except pyjq.PyjqException` for robust error handling.