|
| 1 | +Python JSONPath Read/Write |
| 2 | +========================== |
| 3 | + |
| 4 | +https://github.com/kennknowles/python-jsonpath-rw |
| 5 | + |
| 6 | +This package provides a robust implementation of JSONPath with read and |
| 7 | +update capability as well as additional operators, described below. |
| 8 | + |
| 9 | +This package differs from other JSONPath implementations in that it |
| 10 | +is a full _language_ implementation, meaning the JSONPath expressions |
| 11 | +are first class objects, easy to analyze, transform, parse, print, |
| 12 | +and extend. (You can also execute them :-) |
| 13 | + |
| 14 | + |
| 15 | +JSONPath Syntax |
| 16 | +--------------- |
| 17 | + |
| 18 | +The JSONPath syntax supported by this library includes some additional |
| 19 | +features and omits some problematic features (those that make it unportable). |
| 20 | +In particular, some new operators such as `|` and `where` are available, and parentheses |
| 21 | +are used for grouping not for callbacks into Python, since with these changes |
| 22 | +the language is not trivially associative. Also, fields may be quoted whether or |
| 23 | +not they are contained in brackets. |
| 24 | + |
| 25 | +Atomic expressions: |
| 26 | + |
| 27 | +------------------------------|------------------- |
| 28 | +`$` | The root object |
| 29 | +_field_ | Specified field(s), described below |
| 30 | +`[` _field_ `]` | Same as _field_ |
| 31 | +`[` _idx_ `]` | Array access, described below (this is always unambiguous with field access) |
| 32 | + |
| 33 | +Jsonpath operators: |
| 34 | + |
| 35 | +---------------------------------------|--------------------------------------------------------------------- |
| 36 | +_jsonpath1_ `.` _jsonpath2_ | All nodes matched by _jsonpath2_ starting at any node matching _jsonpath1_ |
| 37 | +_jsonpath_ `[` _whatever_ `]` | Same as _jsonpath_`.`_whatever_ |
| 38 | +_jsonpath1_ `..` _jsonpath2_ | All nodes matched by _jsonpath2_ that descend from any node matching _jsonpath1_ |
| 39 | +_jsonpath1_ `where` _jsonpath2_ | Any nodes matching _jsonpath1_ with a child matching _jsonpath2_ |
| 40 | +_jsonpath1_ `|` _jsonpath2_ | Any node matching either _jsonpath1_ or _jsonpath2_ |
| 41 | + |
| 42 | +Field specifiers (_field_): |
| 43 | + |
| 44 | +----------------------------|---------------------------------------- |
| 45 | +`fieldname` | the field `fieldname` (from the "current" object) |
| 46 | +`"fieldname"` | same as above, for allowing special characters in the fieldname |
| 47 | +`'fieldname'` | ditto |
| 48 | +`*` | any field |
| 49 | +_field_ `,` _field_ | either of the named fields (you can always build equivalent jsonpath using `|`) |
| 50 | + |
| 51 | +Array specifiers (_idx_): |
| 52 | + |
| 53 | +---------------------------------------|---------------------------------------- |
| 54 | + - `[`_n_`]` | array index (may be comma-separated list) |
| 55 | + - `[`_start_`?:`_end_`?]` | array slicing (note that _step_ is unimplemented only due to lack of need thus far) |
| 56 | + - `[*]` | any array index |
| 57 | + |
| 58 | + |
| 59 | +Programmatic JSONPath |
| 60 | +--------------------- |
| 61 | + |
| 62 | +If you are programming in Python and would like a more robust way to create JSONPath |
| 63 | +expressions that does not depend on a parser, it is very easy to do so directly, |
| 64 | +and here are some examples: |
| 65 | + |
| 66 | + - `Root()` |
| 67 | + - `Slice(start=0, end=None, step=None)` |
| 68 | + - `Fields('foo', 'bar')` |
| 69 | + - `Index(42)` |
| 70 | + - `Child(Fields('foo'), Index(42))` |
| 71 | + - `Where(Slice(), Fields('subfield'))` |
| 72 | + - `Descendants(jsonpath, jsonpath)` |
| 73 | + |
| 74 | + |
| 75 | +More to explore |
| 76 | +--------------- |
| 77 | + |
| 78 | +There are way too many jsonpath implementations out there to discuss. |
| 79 | +Some are robust, some are toy projects that still work fine, some are |
| 80 | +exercises. There will undoubtedly be many more. This one is made |
| 81 | +for use in released, maintained code, and in particular for |
| 82 | +programmatic access to the abstract syntax and extension. But |
| 83 | +JSONPath at its simplest just isn't that complicated, so |
| 84 | +you can probably use any of them successfully. Why not this one? |
| 85 | + |
| 86 | +The original proposal, as far as I know: |
| 87 | + |
| 88 | + * [JSONPath - XPath for JSON](http://goessner.net/articles/JSONPath/) by Stefan Goessner. |
| 89 | + |
| 90 | + |
| 91 | +Contributors |
| 92 | +------------ |
| 93 | + |
| 94 | + * [Kenn Knowles](https://github.com/kennknowles) ([@kennknowles](https://twitter.com/KennKnowles)) |
| 95 | + |
| 96 | + |
| 97 | +Copyright and License |
| 98 | +--------------------- |
| 99 | + |
| 100 | +Copyright 2013- Kenneth Knowles |
| 101 | + |
| 102 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 103 | +you may not use this file except in compliance with the License. |
| 104 | +You may obtain a copy of the License at |
| 105 | + |
| 106 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 107 | + |
| 108 | +Unless required by applicable law or agreed to in writing, software |
| 109 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 110 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 111 | +See the License for the specific language governing permissions and |
| 112 | +limitations under the License. |
0 commit comments