1Metadata-Version: 2.1
2Name: pyjq
3Version: 2.4.0
4Summary: Binding for jq JSON processor.
5Home-page: http://github.com/doloopwhile/pyjq
6Author: Omoto Kenji
7License: MIT License
8Description: pyjq: Binding for jq JSON Processor
9        ===================================
10
11        [![CircleCI](https://circleci.com/gh/doloopwhile/pyjq.svg?style=svg)](https://circleci.com/gh/doloopwhile/pyjq)
12
13        pyjq is a Python bindings for jq (<http://stedolan.github.io/jq/>).
14
15        > jq is like sed for JSON data – you can use it to slice and filter and
16        > map and transform structured data with the same ease that sed, awk,
17        > grep and friends let you play with text.
18        >
19        > <http://stedolan.github.io/jq/>
20
21        You can seamlessly call jq script (like regular expression) and process
22        plain python data structure.
23
24        For your information, <https://pypi.python.org/pypi/jq> is a also jq
25        bindings but different and incompatible with pyjq.
26
27        Example
28        -------
29
30        ```python
31        >>> data = dict(
32        ...     parameters= [
33        ...         dict(name="PKG_TAG_NAME", value="trunk"),
34        ...         dict(name="GIT_COMMIT", value="master"),
35        ...         dict(name="TRIGGERED_JOB", value="trunk-buildall")
36        ...     ],
37        ...     id="2013-12-27_00-09-37",
38        ...     changeSet=dict(items=[], kind="git"),
39        ... )
40        >>> import pyjq
41        >>> pyjq.first('.parameters[] | {"param_name": .name, "param_type":.type}', data)
42        {'param_type': None, 'param_name': 'PKG_TAG_NAME'}
43        ```
44
45        Install
46        -------
47
48        It requires build tools such as make, automake, libtool, etc...
49
50        You can install from PyPI by usual way.
51
52            pip install pyjq
53
54        API
55        ---
56
57        For jq script, [see its manual](http://stedolan.github.io/jq/manual/).
58
59        Only four APIs are provided:
60
61        - `all`
62        - `first`
63        - `one`
64        - `compile`
65
66        `all` transforms a value by JSON script and returns all results as a list.
67
68        ```python
69        >>> value = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
70        >>> pyjq.all('{user, title: .titles[]}', value)
71        [{'user': 'stedolan', 'title': 'JQ Primer'}, {'user': 'stedolan', 'title': 'More JQ'}]
72        ```
73
74        `all` takes an optional argument `vars`.
75        `vars` is a dictonary of predefined variables for `script`.
76        The values in `vars` are avaiable in the `script` as a `$key`.
77        That is, `vars` works like `--arg` option and `--argjson` option of jq command.
78        ```python
79        >>> pyjq.all('{user, title: .titles[]} | select(.title == $title)', value, vars={"title": "More JQ"})
80        [{'user': 'stedolan', 'title': 'More JQ'}]
81        ```
82
83        `all` takes an optional argument `url`.
84        If `url` is given, the subject of transformation is got from the `url`.
85
86        ```python
87        >> pyjq.all(".[] | .login", url="https://api.github.com/repos/stedolan/jq/contributors") # get all contributors of jq
88        ['nicowilliams', 'stedolan', 'dtolnay', ... ]
89        ```
90
91        Additionally, `all` takes an optional argument `opener`.
92        The default `opener` will simply download contents by `urllib.request.urlopen` and decode by `json.decode`.
93        However, you can customize this behavior using custom `opener`.
94
95        `first` is almost some to `all` but it `first` returns the first result of transformation.
96
97        ```python
98        >>> value = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
99        >>> pyjq.all('{user, title: .titles[]}', value)
100        [{'user': 'stedolan', 'title': 'JQ Primer'}, {'user': 'stedolan', 'title': 'More JQ'}]
101        ```
102
103        `first` returns `default` when there are no results.
104
105        ```python
106        >>> value = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
107        >>> pyjq.first('.titles[] | select(test("e"))', value) # The first title which is contains "e"
108        'JQ Primer'
109        ```
110
111        `first` returns the first result of transformation. It returns `default` when there are no results.
112
113        ```python
114        >>> value = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
115        >>> pyjq.first('.titles[] | select(test("T"))', value, "Third JS") # The first title which is contains "T"
116        'Third JS'
117        ```
118
119        `one` do also returns the first result of transformation but raise Exception if there are no results.
120
121        ```python
122        >>> value = {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
123        >>> pyjq.one('.titles[] | select(test("T"))', value)
124        IndexError: Result of jq is empty
125        ```
126
127        Limitation
128        ----------
129
130        jq is a JSON Processor. Therefore pyjq is able to process only
131        "JSON compatible" data (object made only from str, int, float, list, dict).
132
133        Q&A
134        ---
135
136        ### How can I process json string got from API by pyjq?
137
138        You should apply `json.loads` in the standard library before pass to pyjq.
139
140        Author
141        ------
142        [OMOTO Kenji](https://github.com/doloopwhile)
143
144        License
145        -------
146
147        Released under the MIT license. See LICENSE for details.
148
149        Development
150        -----------
151
152        ## Pipenv
153
154        This project uses [Pipenv](https://docs.pipenv.org/en/latest/) to manage dependencies.
155
156        Please install development tools with folloing command:
157
158        ```python
159        pipenv install --dev -e
160        ```
161
162        ## We DO commit `_pyjq.c`
163
164        When you edit `_pyjq.pyx`, you need to run `pipenv run cython _pyjq.pyx` before to run `pipenv run python setup.py develop`.
165        It is because `setup.py` in this project does not compile .pyx to .c.
166
167        Of course, we can use `Cython.Build.cythonize` in setup.py to automatically compile .pyx to .c .
168        But, it cause bootstrap problem in ``pip install``.
169
170        So, we DO commit both of `_pyjq.pyx` and `_pyjq.c`.
171
172        License
173        -------
174        MIT License. See [LICENSE](./LICENSE).
175
176        This package includes [jq](https://github.com/stedolan/jq) and [oniguruma](https://github.com/kkos/oniguruma). Their license files are included in archive files.
177
178        - jq: `dependencies/jq-1.5.tar.gz`
179        - oniguruma: `dependencies/onig-6.9.0.tar.gz`
180
181        Changelog
182        ---------
183
184        ### 2.4.0
185
186        - Dropped support for Python 2.7, 3.4, 3.5 (Supports only 3.6+).
187
188        ### 2.3.0
189
190        - Supported WindowsPE(msys)
191
192        ### 2.2.0
193
194        - Added `library_paths=` option.
195
196        ### 2.1.0
197
198        - API's translate JS object not to `dict` but to `collections.OrderedDict`.
199
200        ### 2.0.0
201
202        - Semantic versioning.
203        - Bundle source codes of jq and oniguruma.
204        - Supported Python 3.5.
205        - Dropped support for Python 3.2.
206        - Aeded `all` method.
207
208        ### 1.0
209
210        - First release.
211
212Keywords: jq
213Platform: UNKNOWN
214Classifier: Development Status :: 5 - Production/Stable
215Classifier: Intended Audience :: Developers
216Classifier: Natural Language :: English
217Classifier: License :: OSI Approved :: MIT License
218Classifier: Programming Language :: Python
219Classifier: Programming Language :: Python :: 3
220Classifier: Programming Language :: Python :: 3.6
221Classifier: Programming Language :: Python :: 3.7
222Classifier: Programming Language :: JavaScript
223Description-Content-Type: text/markdown
224