1Python JSONPath RW 2================== 3 4https://github.com/kennknowles/python-jsonpath-rw 5 6|Build Status| |Test coverage| |PyPi version| |PyPi downloads| 7 8This library provides a robust and significantly extended implementation 9of JSONPath for Python. It is tested with Python 2.6, 2.7, 3.2, 3.3. 10*(On travis-ci there is a segfault when running the tests with pypy; I don't think the problem lies with this library)*. 11 12This library differs from other JSONPath implementations in that it is a 13full *language* implementation, meaning the JSONPath expressions are 14first class objects, easy to analyze, transform, parse, print, and 15extend. (You can also execute them :-) 16 17Quick Start 18----------- 19 20To install, use pip: 21 22:: 23 24 $ pip install jsonpath-rw 25 26Then: 27 28.. code:: python 29 30 $ python 31 32 >>> from jsonpath_rw import jsonpath, parse 33 34 # A robust parser, not just a regex. (Makes powerful extensions possible; see below) 35 >>> jsonpath_expr = parse('foo[*].baz') 36 37 # Extracting values is easy 38 >>> [match.value for match in jsonpath_expr.find({'foo': [{'baz': 1}, {'baz': 2}]})] 39 [1, 2] 40 41 # Matches remember where they came from 42 >>> [str(match.full_path) for match in jsonpath_expr.find({'foo': [{'baz': 1}, {'baz': 2}]})] 43 ['foo.[0].baz', 'foo.[1].baz'] 44 45 # And this can be useful for automatically providing ids for bits of data that do not have them (currently a global switch) 46 >>> jsonpath.auto_id_field = 'id' 47 >>> [match.value for match in parse('foo[*].id').find({'foo': [{'id': 'bizzle'}, {'baz': 3}]})] 48 ['foo.bizzle', 'foo.[1]'] 49 50 # A handy extension: named operators like `parent` 51 >>> [match.value for match in parse('a.*.b.`parent`.c').find({'a': {'x': {'b': 1, 'c': 'number one'}, 'y': {'b': 2, 'c': 'number two'}}})] 52 ['number two', 'number one'] 53 54 # You can also build expressions directly quite easily 55 >>> from jsonpath_rw.jsonpath import Fields 56 >>> from jsonpath_rw.jsonpath import Slice 57 58 >>> jsonpath_expr_direct = Fields('foo').child(Slice('*')).child(Fields('baz')) # This is equivalent 59 60JSONPath Syntax 61--------------- 62 63The JSONPath syntax supported by this library includes some additional 64features and omits some problematic features (those that make it 65unportable). In particular, some new operators such as ``|`` and 66``where`` are available, and parentheses are used for grouping not for 67callbacks into Python, since with these changes the language is not 68trivially associative. Also, fields may be quoted whether or not they 69are contained in brackets. 70 71Atomic expressions: 72 73+-----------------------+---------------------------------------------------------------------------------------------+ 74| Syntax | Meaning | 75+=======================+=============================================================================================+ 76| ``$`` | The root object | 77+-----------------------+---------------------------------------------------------------------------------------------+ 78| ```this``` | The "current" object. | 79+-----------------------+---------------------------------------------------------------------------------------------+ 80| ```foo``` | More generally, this syntax allows "named operators" to extend JSONPath is arbitrary ways | 81+-----------------------+---------------------------------------------------------------------------------------------+ 82| *field* | Specified field(s), described below | 83+-----------------------+---------------------------------------------------------------------------------------------+ 84| ``[`` *field* ``]`` | Same as *field* | 85+-----------------------+---------------------------------------------------------------------------------------------+ 86| ``[`` *idx* ``]`` | Array access, described below (this is always unambiguous with field access) | 87+-----------------------+---------------------------------------------------------------------------------------------+ 88 89Jsonpath operators: 90 91+-------------------------------------+------------------------------------------------------------------------------------+ 92| Syntax | Meaning | 93+=====================================+====================================================================================+ 94| *jsonpath1* ``.`` *jsonpath2* | All nodes matched by *jsonpath2* starting at any node matching *jsonpath1* | 95+-------------------------------------+------------------------------------------------------------------------------------+ 96| *jsonpath* ``[`` *whatever* ``]`` | Same as *jsonpath*\ ``.``\ *whatever* | 97+-------------------------------------+------------------------------------------------------------------------------------+ 98| *jsonpath1* ``..`` *jsonpath2* | All nodes matched by *jsonpath2* that descend from any node matching *jsonpath1* | 99+-------------------------------------+------------------------------------------------------------------------------------+ 100| *jsonpath1* ``where`` *jsonpath2* | Any nodes matching *jsonpath1* with a child matching *jsonpath2* | 101+-------------------------------------+------------------------------------------------------------------------------------+ 102| *jsonpath1* ``|`` *jsonpath2* | Any nodes matching the union of *jsonpath1* and *jsonpath2* | 103+-------------------------------------+------------------------------------------------------------------------------------+ 104 105Field specifiers ( *field* ): 106 107+-------------------------+-------------------------------------------------------------------------------------+ 108| Syntax | Meaning | 109+=========================+=====================================================================================+ 110| ``fieldname`` | the field ``fieldname`` (from the "current" object) | 111+-------------------------+-------------------------------------------------------------------------------------+ 112| ``"fieldname"`` | same as above, for allowing special characters in the fieldname | 113+-------------------------+-------------------------------------------------------------------------------------+ 114| ``'fieldname'`` | ditto | 115+-------------------------+-------------------------------------------------------------------------------------+ 116| ``*`` | any field | 117+-------------------------+-------------------------------------------------------------------------------------+ 118| *field* ``,`` *field* | either of the named fields (you can always build equivalent jsonpath using ``|``) | 119+-------------------------+-------------------------------------------------------------------------------------+ 120 121Array specifiers ( *idx* ): 122 123+-----------------------------------------+---------------------------------------------------------------------------------------+ 124| Syntax | Meaning | 125+=========================================+=======================================================================================+ 126| ``[``\ *n*\ ``]`` | array index (may be comma-separated list) | 127+-----------------------------------------+---------------------------------------------------------------------------------------+ 128| ``[``\ *start*\ ``?:``\ *end*\ ``?]`` | array slicing (note that *step* is unimplemented only due to lack of need thus far) | 129+-----------------------------------------+---------------------------------------------------------------------------------------+ 130| ``[*]`` | any array index | 131+-----------------------------------------+---------------------------------------------------------------------------------------+ 132 133Programmatic JSONPath 134--------------------- 135 136If you are programming in Python and would like a more robust way to 137create JSONPath expressions that does not depend on a parser, it is very 138easy to do so directly, and here are some examples: 139 140- ``Root()`` 141- ``Slice(start=0, end=None, step=None)`` 142- ``Fields('foo', 'bar')`` 143- ``Index(42)`` 144- ``Child(Fields('foo'), Index(42))`` 145- ``Where(Slice(), Fields('subfield'))`` 146- ``Descendants(jsonpath, jsonpath)`` 147 148Extensions 149---------- 150 151- *Path data*: The result of ``JsonPath.find`` provide detailed context 152 and path data so it is easy to traverse to parent objects, print full 153 paths to pieces of data, and generate automatic ids. 154- *Automatic Ids*: If you set ``jsonpath_rw.auto_id_field`` to a value 155 other than None, then for any piece of data missing that field, it 156 will be replaced by the JSONPath to it, giving automatic unique ids 157 to any piece of data. These ids will take into account any ids 158 already present as well. 159- *Named operators*: Instead of using ``@`` to reference the currently 160 object, this library uses ```this```. In general, any string 161 contained in backquotes can be made to be a new operator, currently 162 by extending the library. 163 164More to explore 165--------------- 166 167There are way too many jsonpath implementations out there to discuss. 168Some are robust, some are toy projects that still work fine, some are 169exercises. There will undoubtedly be many more. This one is made for use 170in released, maintained code, and in particular for programmatic access 171to the abstract syntax and extension. But JSONPath at its simplest just 172isn't that complicated, so you can probably use any of them 173successfully. Why not this one? 174 175The original proposal, as far as I know: 176 177- `JSONPath - XPath for 178 JSON <http://goessner.net/articles/JSONPath/>`__ by Stefan Goessner. 179 180Special note about PLY and docstrings 181------------------------------------- 182 183The main parsing toolkit underlying this library, 184`PLY <https://github.com/dabeaz/ply>`__, does not work with docstrings 185removed. For example, ``PYTHONOPTIMIZE=2`` and ``python -OO`` will both 186cause a failure. 187 188Contributors 189------------ 190 191This package is authored and maintained by: 192 193- `Kenn Knowles <https://github.com/kennknowles>`__ 194 (`@kennknowles <https://twitter.com/KennKnowles>`__) 195 196with the help of patches submitted by `these contributors <https://github.com/kennknowles/python-jsonpath-rw/graphs/contributors>`__. 197 198Copyright and License 199--------------------- 200 201Copyright 2013- Kenneth Knowles 202 203Licensed under the Apache License, Version 2.0 (the "License"); you may 204not use this file except in compliance with the License. You may obtain 205a copy of the License at 206 207:: 208 209 http://www.apache.org/licenses/LICENSE-2.0 210 211Unless required by applicable law or agreed to in writing, software 212distributed under the License is distributed on an "AS IS" BASIS, 213WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 214See the License for the specific language governing permissions and 215limitations under the License. 216 217.. |Build Status| image:: https://travis-ci.org/kennknowles/python-jsonpath-rw.png?branch=master 218 :target: https://travis-ci.org/kennknowles/python-jsonpath-rw 219.. |Test coverage| image:: https://coveralls.io/repos/kennknowles/python-jsonpath-rw/badge.png?branch=master 220 :target: https://coveralls.io/r/kennknowles/python-jsonpath-rw 221.. |PyPi version| image:: https://pypip.in/v/jsonpath-rw/badge.png 222 :target: https://pypi.python.org/pypi/jsonpath-rw 223.. |PyPi downloads| image:: https://pypip.in/d/jsonpath-rw/badge.png 224 :target: https://pypi.python.org/pypi/jsonpath-rw 225
