pyjq: Binding for jq JSON Processor
===================================
[](https://circleci.com/gh/doloopwhile/pyjq)
pyjq is a Python bindings for jq (<http://stedolan.github.io/jq/>).
> jq is like sed for JSON data - you can use it to slice and filter and
> map and transform structured data with the same ease that sed, awk,
> grep and friends let you play with text.
>
> <http://stedolan.github.io/jq/>
You can seamlessly call jq script (like regular expression) and process
a plain python data structure.
For your information, <https://pypi.python.org/pypi/jq> is another jq
binding which is different and incompatible with pyjq.
Example
-------
```python
>>> 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}
```
Install
-------
You will need flex, bison (3.0 or newer), libtool, make, automake and autoconf to build jq.
Install them by Homebrew, APT or other way.
You can install from PyPI by usual way.
```shell
pip install pyjq
```
API
---
For jq script, [see its manual](http://stedolan.github.io/jq/manual/).
Only four APIs are provided:
- `all`
- `first`
- `one`
- `compile`
`all` transforms a value by JSON script and returns all results as a list.
```python
>>> 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` takes an optional argument `vars`.
`vars` is a dictonary of predefined variables for `script`.
The values in `vars` are available in the `script` as a `$key`.
That is, `vars` works like `--arg` option and `--argjson` option of jq command.
```python
>>> pyjq.all('{user, title: .titles[]} | select(.title == $title)', value, vars={"title": "More JQ"})
[{'user': 'stedolan', 'title': 'More JQ'}]
```
`all` takes an optional argument `url`.
If `url` is given, the subject of transformation is retrieved from the `url`.
```python
>> pyjq.all(".[] | .login", url="https://api.github.com/repos/stedolan/jq/contributors") # get all contributors of jq
['nicowilliams', 'stedolan', 'dtolnay', ... ]
```
Additionally, `all` takes an optional argument `opener`.
The default `opener` will download contents using `urllib.request.urlopen` and decode using `json.decode`.
However, you can customize this behavior using a custom `opener`.
`first` and `one` are similar to to `all`.
`first` returns the first result of transformation.
When there are no results, `first` returns `None` or the given `default`.
```python
>>> 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` returns the only result of a transformation.
It raises an exception when there are no results or when there are two or more results.
```python
>>> 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` is similar to `re.compile`. It accepts jq script and returns an object with methods.
```python
>>> 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'}]
```
Limitations
-----------
jq is a JSON Processor. Therefore pyjq is able to process only
"JSON compatible" data (object made only from str, int, float, list, dict).
Q&A
---
### How can I process a json string (f.e. gotten from an API) with pyjq?
You should call `json.loads` from the standard library on the string, before you pass it to pyjq.
Author
------
[OMOTO Kenji](https://github.com/doloopwhile)
License
-------
MIT License. See [LICENSE](./LICENSE).
This package includes [jq](https://github.com/stedolan/jq) and [oniguruma](https://github.com/kkos/oniguruma). Their license files are included in their respective archive files.
- jq: `dependencies/jq-1.5.tar.gz`
- oniguruma: `dependencies/onig-6.9.0.tar.gz`
Changelog
---------
### 2.6.0
- Supports 3.10
### 2.5.1
- Fixed typo.
### 2.5.0
- Supports only 3.7+.
- Added pyjq.ScriptRuntimeError.
### 2.4.0
- Dropped support for Python 2.7, 3.4, 3.5 (Supports only 3.6+).
### 2.3.0
- Supported WindowsPE(msys)
### 2.2.0
- Added `library_paths=` option.
### 2.1.0
- API's translate JS object not to `dict` but to `collections.OrderedDict`.
### 2.0.0
- Semantic versioning.
- Bundle source codes of jq and oniguruma.
- Supported Python 3.5.
- Dropped support for Python 3.2.
- Aeded `all` method.
### 1.0
- First release.
Raw data
{
"_id": null,
"home_page": "http://github.com/doloopwhile/pyjq",
"name": "pyjq",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "jq",
"author": "Omoto Kenji",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/8e/a7/678a3f5d458c9c1002adf4938a5df830448254423095ce68d2171abf5b21/pyjq-2.6.0.tar.gz",
"platform": null,
"description": "pyjq: Binding for jq JSON Processor\n===================================\n\n[](https://circleci.com/gh/doloopwhile/pyjq)\n\npyjq is a Python bindings for jq (<http://stedolan.github.io/jq/>).\n\n> jq is like sed for JSON data - you can use it to slice and filter and\n> map and transform structured data with the same ease that sed, awk,\n> grep and friends let you play with text.\n>\n> <http://stedolan.github.io/jq/>\n\nYou can seamlessly call jq script (like regular expression) and process\na plain python data structure.\n\nFor your information, <https://pypi.python.org/pypi/jq> is another jq\nbinding which is different and incompatible with pyjq.\n\nExample\n-------\n\n```python\n>>> data = dict(\n... parameters= [\n... dict(name=\"PKG_TAG_NAME\", value=\"trunk\"),\n... dict(name=\"GIT_COMMIT\", value=\"master\"),\n... dict(name=\"TRIGGERED_JOB\", value=\"trunk-buildall\")\n... ],\n... id=\"2013-12-27_00-09-37\",\n... changeSet=dict(items=[], kind=\"git\"),\n... )\n>>> import pyjq\n>>> pyjq.first('.parameters[] | {\"param_name\": .name, \"param_type\":.type}', data)\n{'param_name': 'PKG_TAG_NAME', 'param_type': None}\n\n```\n\nInstall\n-------\n\nYou will need flex, bison (3.0 or newer), libtool, make, automake and autoconf to build jq.\nInstall them by Homebrew, APT or other way.\n\nYou can install from PyPI by usual way.\n\n```shell\npip install pyjq\n```\n\nAPI\n---\n\nFor jq script, [see its manual](http://stedolan.github.io/jq/manual/).\n\nOnly four APIs are provided:\n\n- `all`\n- `first`\n- `one`\n- `compile`\n\n`all` transforms a value by JSON script and returns all results as a list.\n\n```python\n>>> value = {\"user\":\"stedolan\",\"titles\":[\"JQ Primer\", \"More JQ\"]}\n>>> pyjq.all('{user, title: .titles[]}', value)\n[{'user': 'stedolan', 'title': 'JQ Primer'}, {'user': 'stedolan', 'title': 'More JQ'}]\n```\n\n`all` takes an optional argument `vars`.\n`vars` is a dictonary of predefined variables for `script`.\nThe values in `vars` are available in the `script` as a `$key`.\nThat is, `vars` works like `--arg` option and `--argjson` option of jq command.\n\n```python\n>>> pyjq.all('{user, title: .titles[]} | select(.title == $title)', value, vars={\"title\": \"More JQ\"})\n[{'user': 'stedolan', 'title': 'More JQ'}]\n```\n\n`all` takes an optional argument `url`.\nIf `url` is given, the subject of transformation is retrieved from the `url`.\n\n```python\n>> pyjq.all(\".[] | .login\", url=\"https://api.github.com/repos/stedolan/jq/contributors\") # get all contributors of jq\n['nicowilliams', 'stedolan', 'dtolnay', ... ]\n```\n\nAdditionally, `all` takes an optional argument `opener`.\nThe default `opener` will download contents using `urllib.request.urlopen` and decode using `json.decode`.\nHowever, you can customize this behavior using a custom `opener`.\n\n`first` and `one` are similar to to `all`.\n\n`first` returns the first result of transformation.\nWhen there are no results, `first` returns `None` or the given `default`.\n\n```python\n>>> data = {\"user\":\"stedolan\",\"titles\":[\"JQ Primer\", \"More JQ\"]}\n>>> pyjq.first('{user, title: .titles[]}', data)\n{'user': 'stedolan', 'title': 'JQ Primer'}\n>>> pyjq.first('.titles[] | select(test(\"T\"))', data) # returns None\n>>> pyjq.first('.titles[] | select(test(\"T\"))', data, default=\"Third JS\")\n'Third JS'\n```\n\n`one` returns the only result of a transformation.\nIt raises an exception when there are no results or when there are two or more results.\n\n```python\n>>> data = {\"user\":\"stedolan\",\"titles\": [\"JQ Primer\", \"More JQ\"]}\n>>> pyjq.one('.titles[] | select(test(\"P\"))', data)\n'JQ Primer'\n>>> pyjq.one('.titles[] | select(test(\"T\"))', data)\nTraceback (most recent call last):\nIndexError: Result of jq is empty\n>>> pyjq.one('.titles[] | select(test(\"J\"))', data)\nTraceback (most recent call last):\nIndexError: Result of jq have multiple elements\n```\n\n`compile` is similar to `re.compile`. It accepts jq script and returns an object with methods.\n\n```python\n>>> data = {\"user\":\"stedolan\",\"titles\":[\"JQ Primer\", \"More JQ\"]}\n>>> import pyjq\n>>> pat = pyjq.compile('{user, title: .titles[]}')\n>>> pat.all(data)\n[{'user': 'stedolan', 'title': 'JQ Primer'}, {'user': 'stedolan', 'title': 'More JQ'}]\n```\n\nLimitations\n-----------\n\njq is a JSON Processor. Therefore pyjq is able to process only\n\"JSON compatible\" data (object made only from str, int, float, list, dict).\n\nQ&A\n---\n\n### How can I process a json string (f.e. gotten from an API) with pyjq?\n\nYou should call `json.loads` from the standard library on the string, before you pass it to pyjq.\n\nAuthor\n------\n[OMOTO Kenji](https://github.com/doloopwhile)\n\nLicense\n-------\nMIT License. See [LICENSE](./LICENSE).\n\nThis package includes [jq](https://github.com/stedolan/jq) and [oniguruma](https://github.com/kkos/oniguruma). Their license files are included in their respective archive files.\n\n- jq: `dependencies/jq-1.5.tar.gz`\n- oniguruma: `dependencies/onig-6.9.0.tar.gz`\n\nChangelog\n---------\n\n### 2.6.0\n\n- Supports 3.10\n\n### 2.5.1\n\n- Fixed typo.\n\n### 2.5.0\n\n- Supports only 3.7+.\n- Added pyjq.ScriptRuntimeError.\n\n### 2.4.0\n\n- Dropped support for Python 2.7, 3.4, 3.5 (Supports only 3.6+).\n\n### 2.3.0\n\n- Supported WindowsPE(msys)\n\n### 2.2.0\n\n- Added `library_paths=` option.\n\n### 2.1.0\n\n- API's translate JS object not to `dict` but to `collections.OrderedDict`.\n\n### 2.0.0\n\n- Semantic versioning.\n- Bundle source codes of jq and oniguruma.\n- Supported Python 3.5.\n- Dropped support for Python 3.2.\n- Aeded `all` method.\n\n### 1.0\n\n- First release.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Binding for jq JSON processor.",
"version": "2.6.0",
"split_keywords": [
"jq"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "7c5cd42e5f883b7380662fc27bfbf0dc",
"sha256": "6e0e4f398e81b1fb9794874d81fc9240d4a155adba5a1aecda77e717bcfae03e"
},
"downloads": -1,
"filename": "pyjq-2.6.0-cp310-cp310-macosx_12_0_x86_64.whl",
"has_sig": false,
"md5_digest": "7c5cd42e5f883b7380662fc27bfbf0dc",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": null,
"size": 315939,
"upload_time": "2022-08-02T03:53:44",
"upload_time_iso_8601": "2022-08-02T03:53:44.265223Z",
"url": "https://files.pythonhosted.org/packages/12/12/b1016128aed3ee6419b6aaa681e6a795747042a4b5eb24fc28bbe872484c/pyjq-2.6.0-cp310-cp310-macosx_12_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "ecd20a9ee2eee10b032947868063c0d8",
"sha256": "e083f326f4af8b07b8ca6424d1f99afbdd7db9b727284da5f919b9816077f2e4"
},
"downloads": -1,
"filename": "pyjq-2.6.0.tar.gz",
"has_sig": false,
"md5_digest": "ecd20a9ee2eee10b032947868063c0d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2035396,
"upload_time": "2022-08-02T03:53:47",
"upload_time_iso_8601": "2022-08-02T03:53:47.172886Z",
"url": "https://files.pythonhosted.org/packages/8e/a7/678a3f5d458c9c1002adf4938a5df830448254423095ce68d2171abf5b21/pyjq-2.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-08-02 03:53:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "doloopwhile",
"github_project": "pyjq",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "pyjq"
}
JSON
