Python JSONPath RW
==================
https://github.com/kennknowles/python-jsonpath-rw
|Build Status| |Test coverage| |PyPi version| |PyPi downloads|
This library provides a robust and significantly extended implementation
of JSONPath for Python. It is tested with Python 2.6, 2.7, 3.2, 3.3.
*(On travis-ci there is a segfault when running the tests with pypy; I don't think the problem lies with this library)*.
This library differs from other JSONPath implementations in that it is a
full *language* implementation, meaning the JSONPath expressions are
first class objects, easy to analyze, transform, parse, print, and
extend. (You can also execute them :-)
Quick Start
-----------
To install, use pip:
::
$ pip install jsonpath-rw
Then:
.. code:: python
$ python
>>> from jsonpath_rw import jsonpath, parse
# A robust parser, not just a regex. (Makes powerful extensions possible; see below)
>>> jsonpath_expr = parse('foo[*].baz')
# Extracting values is easy
>>> [match.value for match in jsonpath_expr.find({'foo': [{'baz': 1}, {'baz': 2}]})]
[1, 2]
# Matches remember where they came from
>>> [str(match.full_path) for match in jsonpath_expr.find({'foo': [{'baz': 1}, {'baz': 2}]})]
['foo.[0].baz', 'foo.[1].baz']
# And this can be useful for automatically providing ids for bits of data that do not have them (currently a global switch)
>>> jsonpath.auto_id_field = 'id'
>>> [match.value for match in parse('foo[*].id').find({'foo': [{'id': 'bizzle'}, {'baz': 3}]})]
['foo.bizzle', 'foo.[1]']
# A handy extension: named operators like `parent`
>>> [match.value for match in parse('a.*.b.`parent`.c').find({'a': {'x': {'b': 1, 'c': 'number one'}, 'y': {'b': 2, 'c': 'number two'}}})]
['number two', 'number one']
# You can also build expressions directly quite easily
>>> from jsonpath_rw.jsonpath import Fields
>>> from jsonpath_rw.jsonpath import Slice
>>> jsonpath_expr_direct = Fields('foo').child(Slice('*')).child(Fields('baz')) # This is equivalent
JSONPath Syntax
---------------
The JSONPath syntax supported by this library includes some additional
features and omits some problematic features (those that make it
unportable). In particular, some new operators such as ``|`` and
``where`` are available, and parentheses are used for grouping not for
callbacks into Python, since with these changes the language is not
trivially associative. Also, fields may be quoted whether or not they
are contained in brackets.
Atomic expressions:
+-----------------------+---------------------------------------------------------------------------------------------+
| Syntax | Meaning |
+=======================+=============================================================================================+
| ``$`` | The root object |
+-----------------------+---------------------------------------------------------------------------------------------+
| ```this``` | The "current" object. |
+-----------------------+---------------------------------------------------------------------------------------------+
| ```foo``` | More generally, this syntax allows "named operators" to extend JSONPath is arbitrary ways |
+-----------------------+---------------------------------------------------------------------------------------------+
| *field* | Specified field(s), described below |
+-----------------------+---------------------------------------------------------------------------------------------+
| ``[`` *field* ``]`` | Same as *field* |
+-----------------------+---------------------------------------------------------------------------------------------+
| ``[`` *idx* ``]`` | Array access, described below (this is always unambiguous with field access) |
+-----------------------+---------------------------------------------------------------------------------------------+
Jsonpath operators:
+-------------------------------------+------------------------------------------------------------------------------------+
| Syntax | Meaning |
+=====================================+====================================================================================+
| *jsonpath1* ``.`` *jsonpath2* | All nodes matched by *jsonpath2* starting at any node matching *jsonpath1* |
+-------------------------------------+------------------------------------------------------------------------------------+
| *jsonpath* ``[`` *whatever* ``]`` | Same as *jsonpath*\ ``.``\ *whatever* |
+-------------------------------------+------------------------------------------------------------------------------------+
| *jsonpath1* ``..`` *jsonpath2* | All nodes matched by *jsonpath2* that descend from any node matching *jsonpath1* |
+-------------------------------------+------------------------------------------------------------------------------------+
| *jsonpath1* ``where`` *jsonpath2* | Any nodes matching *jsonpath1* with a child matching *jsonpath2* |
+-------------------------------------+------------------------------------------------------------------------------------+
| *jsonpath1* ``|`` *jsonpath2* | Any nodes matching the union of *jsonpath1* and *jsonpath2* |
+-------------------------------------+------------------------------------------------------------------------------------+
Field specifiers ( *field* ):
+-------------------------+-------------------------------------------------------------------------------------+
| Syntax | Meaning |
+=========================+=====================================================================================+
| ``fieldname`` | the field ``fieldname`` (from the "current" object) |
+-------------------------+-------------------------------------------------------------------------------------+
| ``"fieldname"`` | same as above, for allowing special characters in the fieldname |
+-------------------------+-------------------------------------------------------------------------------------+
| ``'fieldname'`` | ditto |
+-------------------------+-------------------------------------------------------------------------------------+
| ``*`` | any field |
+-------------------------+-------------------------------------------------------------------------------------+
| *field* ``,`` *field* | either of the named fields (you can always build equivalent jsonpath using ``|``) |
+-------------------------+-------------------------------------------------------------------------------------+
Array specifiers ( *idx* ):
+-----------------------------------------+---------------------------------------------------------------------------------------+
| Syntax | Meaning |
+=========================================+=======================================================================================+
| ``[``\ *n*\ ``]`` | array index (may be comma-separated list) |
+-----------------------------------------+---------------------------------------------------------------------------------------+
| ``[``\ *start*\ ``?:``\ *end*\ ``?]`` | array slicing (note that *step* is unimplemented only due to lack of need thus far) |
+-----------------------------------------+---------------------------------------------------------------------------------------+
| ``[*]`` | any array index |
+-----------------------------------------+---------------------------------------------------------------------------------------+
Programmatic JSONPath
---------------------
If you are programming in Python and would like a more robust way to
create JSONPath expressions that does not depend on a parser, it is very
easy to do so directly, and here are some examples:
- ``Root()``
- ``Slice(start=0, end=None, step=None)``
- ``Fields('foo', 'bar')``
- ``Index(42)``
- ``Child(Fields('foo'), Index(42))``
- ``Where(Slice(), Fields('subfield'))``
- ``Descendants(jsonpath, jsonpath)``
Extensions
----------
- *Path data*: The result of ``JsonPath.find`` provide detailed context
and path data so it is easy to traverse to parent objects, print full
paths to pieces of data, and generate automatic ids.
- *Automatic Ids*: If you set ``jsonpath_rw.auto_id_field`` to a value
other than None, then for any piece of data missing that field, it
will be replaced by the JSONPath to it, giving automatic unique ids
to any piece of data. These ids will take into account any ids
already present as well.
- *Named operators*: Instead of using ``@`` to reference the currently
object, this library uses ```this```. In general, any string
contained in backquotes can be made to be a new operator, currently
by extending the library.
More to explore
---------------
There are way too many jsonpath implementations out there to discuss.
Some are robust, some are toy projects that still work fine, some are
exercises. There will undoubtedly be many more. This one is made for use
in released, maintained code, and in particular for programmatic access
to the abstract syntax and extension. But JSONPath at its simplest just
isn't that complicated, so you can probably use any of them
successfully. Why not this one?
The original proposal, as far as I know:
- `JSONPath - XPath for
JSON <http://goessner.net/articles/JSONPath/>`__ by Stefan Goessner.
Special note about PLY and docstrings
-------------------------------------
The main parsing toolkit underlying this library,
`PLY <https://github.com/dabeaz/ply>`__, does not work with docstrings
removed. For example, ``PYTHONOPTIMIZE=2`` and ``python -OO`` will both
cause a failure.
Contributors
------------
This package is authored and maintained by:
- `Kenn Knowles <https://github.com/kennknowles>`__
(`@kennknowles <https://twitter.com/KennKnowles>`__)
with the help of patches submitted by `these contributors <https://github.com/kennknowles/python-jsonpath-rw/graphs/contributors>`__.
Copyright and License
---------------------
Copyright 2013- Kenneth Knowles
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
::
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.. |Build Status| image:: https://travis-ci.org/kennknowles/python-jsonpath-rw.png?branch=master
:target: https://travis-ci.org/kennknowles/python-jsonpath-rw
.. |Test coverage| image:: https://coveralls.io/repos/kennknowles/python-jsonpath-rw/badge.png?branch=master
:target: https://coveralls.io/r/kennknowles/python-jsonpath-rw
.. |PyPi version| image:: https://pypip.in/v/jsonpath-rw/badge.png
:target: https://pypi.python.org/pypi/jsonpath-rw
.. |PyPi downloads| image:: https://pypip.in/d/jsonpath-rw/badge.png
:target: https://pypi.python.org/pypi/jsonpath-rw
Raw data
{
"_id": null,
"home_page": "https://github.com/kennknowles/python-jsonpath-rw",
"name": "jsonpath-rw",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Kenneth Knowles",
"author_email": "kenn.knowles@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/7c/45001b1f19af8c4478489fbae4fc657b21c4c669d7a5a036a86882581d85/jsonpath-rw-1.4.0.tar.gz",
"platform": "UNKNOWN",
"description": "Python JSONPath RW\n==================\n\nhttps://github.com/kennknowles/python-jsonpath-rw\n\n|Build Status| |Test coverage| |PyPi version| |PyPi downloads|\n\nThis library provides a robust and significantly extended implementation\nof JSONPath for Python. It is tested with Python 2.6, 2.7, 3.2, 3.3. \n*(On travis-ci there is a segfault when running the tests with pypy; I don't think the problem lies with this library)*.\n\nThis library differs from other JSONPath implementations in that it is a\nfull *language* implementation, meaning the JSONPath expressions are\nfirst class objects, easy to analyze, transform, parse, print, and\nextend. (You can also execute them :-)\n\nQuick Start\n-----------\n\nTo install, use pip:\n\n::\n\n $ pip install jsonpath-rw\n\nThen:\n\n.. code:: python\n\n $ python\n\n >>> from jsonpath_rw import jsonpath, parse\n\n # A robust parser, not just a regex. (Makes powerful extensions possible; see below)\n >>> jsonpath_expr = parse('foo[*].baz')\n\n # Extracting values is easy\n >>> [match.value for match in jsonpath_expr.find({'foo': [{'baz': 1}, {'baz': 2}]})]\n [1, 2]\n\n # Matches remember where they came from\n >>> [str(match.full_path) for match in jsonpath_expr.find({'foo': [{'baz': 1}, {'baz': 2}]})]\n ['foo.[0].baz', 'foo.[1].baz']\n\n # And this can be useful for automatically providing ids for bits of data that do not have them (currently a global switch)\n >>> jsonpath.auto_id_field = 'id'\n >>> [match.value for match in parse('foo[*].id').find({'foo': [{'id': 'bizzle'}, {'baz': 3}]})]\n ['foo.bizzle', 'foo.[1]']\n\n # A handy extension: named operators like `parent`\n >>> [match.value for match in parse('a.*.b.`parent`.c').find({'a': {'x': {'b': 1, 'c': 'number one'}, 'y': {'b': 2, 'c': 'number two'}}})]\n ['number two', 'number one']\n\n # You can also build expressions directly quite easily \n >>> from jsonpath_rw.jsonpath import Fields\n >>> from jsonpath_rw.jsonpath import Slice\n\n >>> jsonpath_expr_direct = Fields('foo').child(Slice('*')).child(Fields('baz')) # This is equivalent\n\nJSONPath Syntax\n---------------\n\nThe JSONPath syntax supported by this library includes some additional\nfeatures and omits some problematic features (those that make it\nunportable). In particular, some new operators such as ``|`` and\n``where`` are available, and parentheses are used for grouping not for\ncallbacks into Python, since with these changes the language is not\ntrivially associative. Also, fields may be quoted whether or not they\nare contained in brackets.\n\nAtomic expressions:\n\n+-----------------------+---------------------------------------------------------------------------------------------+\n| Syntax | Meaning |\n+=======================+=============================================================================================+\n| ``$`` | The root object |\n+-----------------------+---------------------------------------------------------------------------------------------+\n| ```this``` | The \"current\" object. |\n+-----------------------+---------------------------------------------------------------------------------------------+\n| ```foo``` | More generally, this syntax allows \"named operators\" to extend JSONPath is arbitrary ways |\n+-----------------------+---------------------------------------------------------------------------------------------+\n| *field* | Specified field(s), described below |\n+-----------------------+---------------------------------------------------------------------------------------------+\n| ``[`` *field* ``]`` | Same as *field* |\n+-----------------------+---------------------------------------------------------------------------------------------+\n| ``[`` *idx* ``]`` | Array access, described below (this is always unambiguous with field access) |\n+-----------------------+---------------------------------------------------------------------------------------------+\n\nJsonpath operators:\n\n+-------------------------------------+------------------------------------------------------------------------------------+\n| Syntax | Meaning |\n+=====================================+====================================================================================+\n| *jsonpath1* ``.`` *jsonpath2* | All nodes matched by *jsonpath2* starting at any node matching *jsonpath1* |\n+-------------------------------------+------------------------------------------------------------------------------------+\n| *jsonpath* ``[`` *whatever* ``]`` | Same as *jsonpath*\\ ``.``\\ *whatever* |\n+-------------------------------------+------------------------------------------------------------------------------------+\n| *jsonpath1* ``..`` *jsonpath2* | All nodes matched by *jsonpath2* that descend from any node matching *jsonpath1* |\n+-------------------------------------+------------------------------------------------------------------------------------+\n| *jsonpath1* ``where`` *jsonpath2* | Any nodes matching *jsonpath1* with a child matching *jsonpath2* |\n+-------------------------------------+------------------------------------------------------------------------------------+\n| *jsonpath1* ``|`` *jsonpath2* | Any nodes matching the union of *jsonpath1* and *jsonpath2* |\n+-------------------------------------+------------------------------------------------------------------------------------+\n\nField specifiers ( *field* ):\n\n+-------------------------+-------------------------------------------------------------------------------------+\n| Syntax | Meaning |\n+=========================+=====================================================================================+\n| ``fieldname`` | the field ``fieldname`` (from the \"current\" object) |\n+-------------------------+-------------------------------------------------------------------------------------+\n| ``\"fieldname\"`` | same as above, for allowing special characters in the fieldname |\n+-------------------------+-------------------------------------------------------------------------------------+\n| ``'fieldname'`` | ditto |\n+-------------------------+-------------------------------------------------------------------------------------+\n| ``*`` | any field |\n+-------------------------+-------------------------------------------------------------------------------------+\n| *field* ``,`` *field* | either of the named fields (you can always build equivalent jsonpath using ``|``) |\n+-------------------------+-------------------------------------------------------------------------------------+\n\nArray specifiers ( *idx* ):\n\n+-----------------------------------------+---------------------------------------------------------------------------------------+\n| Syntax | Meaning |\n+=========================================+=======================================================================================+\n| ``[``\\ *n*\\ ``]`` | array index (may be comma-separated list) |\n+-----------------------------------------+---------------------------------------------------------------------------------------+\n| ``[``\\ *start*\\ ``?:``\\ *end*\\ ``?]`` | array slicing (note that *step* is unimplemented only due to lack of need thus far) |\n+-----------------------------------------+---------------------------------------------------------------------------------------+\n| ``[*]`` | any array index |\n+-----------------------------------------+---------------------------------------------------------------------------------------+\n\nProgrammatic JSONPath\n---------------------\n\nIf you are programming in Python and would like a more robust way to\ncreate JSONPath expressions that does not depend on a parser, it is very\neasy to do so directly, and here are some examples:\n\n- ``Root()``\n- ``Slice(start=0, end=None, step=None)``\n- ``Fields('foo', 'bar')``\n- ``Index(42)``\n- ``Child(Fields('foo'), Index(42))``\n- ``Where(Slice(), Fields('subfield'))``\n- ``Descendants(jsonpath, jsonpath)``\n\nExtensions\n----------\n\n- *Path data*: The result of ``JsonPath.find`` provide detailed context\n and path data so it is easy to traverse to parent objects, print full\n paths to pieces of data, and generate automatic ids.\n- *Automatic Ids*: If you set ``jsonpath_rw.auto_id_field`` to a value\n other than None, then for any piece of data missing that field, it\n will be replaced by the JSONPath to it, giving automatic unique ids\n to any piece of data. These ids will take into account any ids\n already present as well.\n- *Named operators*: Instead of using ``@`` to reference the currently\n object, this library uses ```this```. In general, any string\n contained in backquotes can be made to be a new operator, currently\n by extending the library.\n\nMore to explore\n---------------\n\nThere are way too many jsonpath implementations out there to discuss.\nSome are robust, some are toy projects that still work fine, some are\nexercises. There will undoubtedly be many more. This one is made for use\nin released, maintained code, and in particular for programmatic access\nto the abstract syntax and extension. But JSONPath at its simplest just\nisn't that complicated, so you can probably use any of them\nsuccessfully. Why not this one?\n\nThe original proposal, as far as I know:\n\n- `JSONPath - XPath for\n JSON <http://goessner.net/articles/JSONPath/>`__ by Stefan Goessner.\n\nSpecial note about PLY and docstrings\n-------------------------------------\n\nThe main parsing toolkit underlying this library,\n`PLY <https://github.com/dabeaz/ply>`__, does not work with docstrings\nremoved. For example, ``PYTHONOPTIMIZE=2`` and ``python -OO`` will both\ncause a failure.\n\nContributors\n------------\n\nThis package is authored and maintained by:\n\n- `Kenn Knowles <https://github.com/kennknowles>`__\n (`@kennknowles <https://twitter.com/KennKnowles>`__)\n \nwith the help of patches submitted by `these contributors <https://github.com/kennknowles/python-jsonpath-rw/graphs/contributors>`__.\n\nCopyright and License\n---------------------\n\nCopyright 2013- Kenneth Knowles\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may\nnot use this file except in compliance with the License. You may obtain\na copy of the License at\n\n::\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n.. |Build Status| image:: https://travis-ci.org/kennknowles/python-jsonpath-rw.png?branch=master\n :target: https://travis-ci.org/kennknowles/python-jsonpath-rw\n.. |Test coverage| image:: https://coveralls.io/repos/kennknowles/python-jsonpath-rw/badge.png?branch=master\n :target: https://coveralls.io/r/kennknowles/python-jsonpath-rw\n.. |PyPi version| image:: https://pypip.in/v/jsonpath-rw/badge.png\n :target: https://pypi.python.org/pypi/jsonpath-rw\n.. |PyPi downloads| image:: https://pypip.in/d/jsonpath-rw/badge.png\n :target: https://pypi.python.org/pypi/jsonpath-rw",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A robust and significantly extended implementation of JSONPath for Python, with a clear AST for metaprogramming.",
"version": "1.4.0",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "https://github.com/kennknowles/python-jsonpath-rw"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "717c45001b1f19af8c4478489fbae4fc657b21c4c669d7a5a036a86882581d85",
"md5": "3a807e05c2c12158fc6bb0a402fd5778",
"sha256": "05c471281c45ae113f6103d1268ec7a4831a2e96aa80de45edc89b11fac4fbec"
},
"downloads": -1,
"filename": "jsonpath-rw-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "3a807e05c2c12158fc6bb0a402fd5778",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13814,
"upload_time": "2015-04-19T01:47:15",
"upload_time_iso_8601": "2015-04-19T01:47:15.060153Z",
"url": "https://files.pythonhosted.org/packages/71/7c/45001b1f19af8c4478489fbae4fc657b21c4c669d7a5a036a86882581d85/jsonpath-rw-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2015-04-19 01:47:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kennknowles",
"github_project": "python-jsonpath-rw",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"lcname": "jsonpath-rw"
}
JSON
