{"id":19825583,"url":"https://github.com/sean2077/jsonpath-python","last_synced_at":"2025-11-23T19:02:43.745Z","repository":{"id":43195867,"uuid":"324299307","full_name":"sean2077/jsonpath-python","owner":"sean2077","description":"A more powerful JSONPath implementations in modern python.","archived":false,"fork":false,"pushed_at":"2022-03-14T02:34:50.000Z","size":75,"stargazers_count":37,"open_issues_count":9,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-20T03:04:47.955Z","etag":null,"topics":["json","jsonpath-syntax"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sean2077.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-25T06:06:45.000Z","updated_at":"2024-12-16T01:51:09.000Z","dependencies_parsed_at":"2022-08-31T15:11:33.092Z","dependency_job_id":null,"html_url":"https://github.com/sean2077/jsonpath-python","commit_stats":null,"previous_names":["sean2077/jsonpath-python","zhangxianbing/jsonpath-python"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Fjsonpath-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Fjsonpath-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Fjsonpath-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Fjsonpath-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sean2077","download_url":"https://codeload.github.com/sean2077/jsonpath-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251889935,"owners_count":21660415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","jsonpath-syntax"],"created_at":"2024-11-12T11:08:08.378Z","updated_at":"2025-11-23T19:02:43.739Z","avatar_url":"https://github.com/sean2077.png","language":"Python","readme":"# jsonpath-python\n\n[![CI](https://github.com/sean2077/jsonpath-python/workflows/CI/badge.svg)](https://github.com/sean2077/jsonpath-python/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/sean2077/jsonpath-python/branch/main/graph/badge.svg)](https://codecov.io/gh/sean2077/jsonpath-python)\n[![PyPI version](https://badge.fury.io/py/jsonpath-python.svg)](https://badge.fury.io/py/jsonpath-python)\n[![Python versions](https://img.shields.io/pypi/pyversions/jsonpath-python.svg)](https://pypi.org/project/jsonpath-python/)\n[![License](https://img.shields.io/github/license/sean2077/jsonpath-python.svg)](https://github.com/sean2077/jsonpath-python/blob/main/LICENSE)\n\nA lightweight and powerful JSONPath implementation for Python.\n\n## Why jsonpath-python?\n\nThere are already several JSONPath libraries in Python, so why choose this one?\n\n1.  **Lightweight \u0026 Zero Dependency**: Unlike `jsonpath-ng` which relies on complex AST parsing frameworks like `ply`, `jsonpath-python` is implemented with pure Python string parsing. It has **zero third-party dependencies**, making it incredibly easy to integrate into any environment.\n2.  **Simple \u0026 Pythonic**: The implementation is straightforward and linear. If you encounter a bug or need to extend it, the code is easy to read and modify. You can even copy the core file directly into your project as a utility.\n3.  **Powerful Features**: It supports advanced features like **sorting**, **filtering**, and **updating** JSON data. If you require strict adherence to the JSONPath standard (RFC 9535), other libraries might be more suitable, but for practical data manipulation, this library offers more power.\n\n## Features\n\n- [x] **Light. (No need to install third-party dependencies.)**\n- [x] **Support filter operator, including multi-selection, inverse-selection filtering.**\n- [x] **Support sorter operator, including sorting by multiple fields, ascending and descending order.**\n- [x] **Support updating JSON data using JSONPath expressions.**\n- [x] Support basic semantics of JSONPath.\n- [x] Support output modes: VALUE, PATH.\n- [x] Support regex filter (`=~`).\n\n## Installation\n\n```bash\npip install jsonpath-python\n\n# import\n\u003e\u003e\u003e from jsonpath import JSONPath\n```\n\n## JSONPath Syntax\n\nThe JSONPath syntax in this project borrows from [JSONPath - XPath for JSON](http://goessner.net/articles/JSONPath/) and is **modified** and **extended** on it.\n\n### Operators\n\n| Operator         | Description                                                                  |\n| ---------------- | ---------------------------------------------------------------------------- |\n| `$`              | the root object/element                                                      |\n| `@`              | the current object/element                                                   |\n| `.` or `[]`      | child operator                                                               |\n| `..`             | recursive descent                                                            |\n| `*`              | wildcard                                                                     |\n| `''`             | (Experimental) wrap field with special character: dots(`.`) and space (` `). |\n| `start:end:step` | array slice operator (It's same as the slice in python)                      |\n| `?()`            | applies a filter expression                                                  |\n| `/()`            | applies a sorter expression                                                  |\n| `()`             | applies a field-extractor expression                                         |\n\n### Examples\n\nBefore running the following example, please import this module and the example data:\n\n```python\n\u003e\u003e\u003e from jsonpath import JSONPath\n\n# For the data used in the following example, please refer to the Appendix part.\n```\n\n#### Select Fields\n\nSelect a field:\n\n```python\n\u003e\u003e\u003e JSONPath(\"$.book\").parse(data)\n[[{'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}, {'category': 'fiction', 'author': 'Evelyn Waugh', 'title': 'Sword of Honour', 'price': 12.99, 'brand': {'version': 'v0.0.1'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}, {'category': 'fiction', 'author': 'J. R. R. Tolkien', 'title': 'The Lord of the Rings', 'isbn': '0-395-19395-8', 'price': 22.99, 'brand': {'version': 'v1.0.3'}}]]\n\u003e\u003e\u003e JSONPath(\"$[book]\").parse(data)\n[[{'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}, {'category': 'fiction', 'author': 'Evelyn Waugh', 'title': 'Sword of Honour', 'price': 12.99, 'brand': {'version': 'v0.0.1'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}, {'category': 'fiction', 'author': 'J. R. R. Tolkien', 'title': 'The Lord of the Rings', 'isbn': '0-395-19395-8', 'price': 22.99, 'brand': {'version': 'v1.0.3'}}]]\n```\n\n(**Experimental**) Select a field with special character: dots(`.`) and space (` `).\n\n```python\n\u003e\u003e\u003e JSONPath(\"$.'a.b c'\").parse(data)\n['a.b c']\n\u003e\u003e\u003e JSONPath(\"$['a.b c']\").parse(data)\n['a.b c']\n```\n\nSelect multiple fields:\n\n```python\n\u003e\u003e\u003e JSONPath(\"$[bicycle,scores]\").parse(data)\n[{'color': 'red', 'price': 19.95}, {'math': {'score': 100, 'avg': 60}, 'english': {'score': 95, 'avg': 80}, 'physic': {'score': 90, 'avg': 70}, 'chemistry': {'score': 85, 'avg': 80}, 'chinese': {'score': 60, 'avg': 75}}]\n```\n\nSelect all fields using wildcard `*`:\n\n```python\n\u003e\u003e\u003e JSONPath(\"$.*\").parse(data)\n['a.b c', [{'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}, {'category': 'fiction', 'author': 'Evelyn Waugh', 'title': 'Sword of Honour', 'price': 12.99, 'brand': {'version': 'v0.0.1'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}, {'category': 'fiction', 'author': 'J. R. R. Tolkien', 'title': 'The Lord of the Rings', 'isbn': '0-395-19395-8', 'price': 22.99, 'brand': {'version': 'v1.0.3'}}], {'color': 'red', 'price': 19.95}, {'math': {'score': 100, 'avg': 60}, 'english': {'score': 95, 'avg': 80}, 'physic': {'score': 90, 'avg': 70}, 'chemistry': {'score': 85, 'avg': 80}, 'chinese': {'score': 60, 'avg': 75}}]\n```\n\n#### Recursive Descent\n\n```python\n\u003e\u003e\u003e JSONPath(\"$..price\").parse(data)\n[8.95, 12.99, 8.99, 22.99, 19.95]\n```\n\n#### Slice\n\nSupport python-like slice.\n\n```python\n\u003e\u003e\u003e JSONPath(\"$.book[1:3]\").parse(data)\n[{'category': 'fiction', 'author': 'Evelyn Waugh', 'title': 'Sword of Honour', 'price': 12.99, 'brand': {'version': 'v0.0.1'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}]\n\u003e\u003e\u003e JSONPath(\"$.book[1:-1]\").parse(data)\n[{'category': 'fiction', 'author': 'Evelyn Waugh', 'title': 'Sword of Honour', 'price': 12.99, 'brand': {'version': 'v0.0.1'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}]\n\u003e\u003e\u003e JSONPath(\"$.book[0:-1:2]\").parse(data)\n[{'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}]\n\u003e\u003e\u003e JSONPath(\"$.book[-1:1]\").parse(data)\n[]\n\u003e\u003e\u003e JSONPath(\"$.book[-1:-11:3]\").parse(data)\n[]\n\u003e\u003e\u003e JSONPath(\"$.book[:]\").parse(data)\n[{'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}, {'category': 'fiction', 'author': 'Evelyn Waugh', 'title': 'Sword of Honour', 'price': 12.99, 'brand': {'version': 'v0.0.1'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}, {'category': 'fiction', 'author': 'J. R. R. Tolkien', 'title': 'The Lord of the Rings', 'isbn': '0-395-19395-8', 'price': 22.99, 'brand': {'version': 'v1.0.3'}}]\n\u003e\u003e\u003e JSONPath(\"$.book[::-1]\").parse(data)\n[{'category': 'fiction', 'author': 'J. R. R. Tolkien', 'title': 'The Lord of the Rings', 'isbn': '0-395-19395-8', 'price': 22.99, 'brand': {'version': 'v1.0.3'}}, {'category': 'fiction', 'author': 'Herman Melville', 'title': 'Moby Dick', 'isbn': '0-553-21311-3', 'price': 8.99, 'brand': {'version': 'v1.0.2'}}, {'category': 'fiction', 'author': 'Evelyn Waugh', 'title': 'Sword of Honour', 'price': 12.99, 'brand': {'version': 'v0.0.1'}}, {'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}]\n\n```\n\n#### Filter Expression\n\nSupport all python comparison operators (`==`, `!=`, `\u003c`, `\u003e`, `\u003e=`, `\u003c=`), python membership operators (`in`, `not in`), python logical operators (`and`, `or`, `not`).\n\n```python\n\u003e\u003e\u003e JSONPath(\"$.book[?(@.price\u003e8 and @.price\u003c9)].price\").parse(data)\n[8.95, 8.99]\n\u003e\u003e\u003e JSONPath('$.book[?(@.category==\"reference\")].category').parse(data)\n['reference']\n\u003e\u003e\u003e JSONPath('$.book[?(@.category!=\"reference\" and @.price\u003c9)].title').parse(data)\n['Moby Dick']\n\u003e\u003e\u003e JSONPath('$.book[?(@.author==\"Herman Melville\" or @.author==\"Evelyn Waugh\")].author').parse(data)\n['Evelyn Waugh', 'Herman Melville']\n\u003e\u003e\u003e JSONPath('$.book[?(@.title =~ /.*Century/)]').parse(data)\n[{'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}]\n```\n\n`Note`: You must use double quote(`\"\"`) instead of single quote(`''`) to wrap the compared string, because single quote(`''`) has another usage in this JSONPath syntax .\n\n#### Sorter Expression\n\nSupport sorting by multiple fields (using operator `,`) and reverse sort (using operator `~`).\n\n```python\n\u003e\u003e\u003e JSONPath(\"$.book[/(price)].price\").parse(data)\n[8.95, 8.99, 12.99, 22.99]\n\u003e\u003e\u003e JSONPath(\"$.book[/(~price)].price\").parse(data)\n[22.99, 12.99, 8.99, 8.95]\n\u003e\u003e\u003e JSONPath(\"$.book[/(category,price)].price\").parse(data)\n[8.99, 12.99, 22.99, 8.95]\n\u003e\u003e\u003e JSONPath(\"$.book[/(brand.version)].brand.version\").parse(data)\n['v0.0.1', 'v1.0.0', 'v1.0.2', 'v1.0.3']\n\u003e\u003e\u003e JSONPath(\"$.scores[/(score)].score\").parse(data)\n[60, 85, 90, 95, 100]\n```\n\n#### Field-Extractor Expression\n\nUsing `(field1,field2,…,filedn)` after a dict object to extract its fields.\n\n```python\n\u003e\u003e\u003e JSONPath(\"$.scores[/(score)].(score)\").parse(data)\n[{'score': 60}, {'score': 85}, {'score': 90}, {'score': 95}, {'score': 100}]\n\u003e\u003e\u003e JSONPath(\"$.book[/(category,price)].(title,price)\").parse(data)\n[{'title': 'Moby Dick', 'price': 8.99}, {'title': 'Sword of Honour', 'price': 12.99}, {'title': 'The Lord of the Rings', 'price': 22.99}, {'title': 'Sayings of the Century', 'price': 8.95}]\n```\n\n#### Update Data\n\nUpdate values in the JSON object using the `update` method.\n\n```python\n# Update with a static value\n\u003e\u003e\u003e JSONPath(\"$.book[*].price\").update(data, 100)\n# Result: All book prices are set to 100\n\n# Update with a function (e.g., apply a discount)\n\u003e\u003e\u003e JSONPath(\"$.book[*].price\").update(data, lambda x: x * 0.9)\n# Result: All book prices are multiplied by 0.9\n```\n\n### Appendix: Example JSON data:\n\n```python\ndata = {\n    \"a.b c\": \"a.b c\",\n    \"book\": [\n        {\n            \"category\": \"reference\",\n            \"author\": \"Nigel Rees\",\n            \"title\": \"Sayings of the Century\",\n            \"price\": 8.95,\n            \"brand\": {\n                \"version\": \"v1.0.0\"\n            }\n        },\n        {\n            \"category\": \"fiction\",\n            \"author\": \"Evelyn Waugh\",\n            \"title\": \"Sword of Honour\",\n            \"price\": 12.99,\n            \"brand\": {\n                \"version\": \"v0.0.1\"\n            }\n        },\n        {\n            \"category\": \"fiction\",\n            \"author\": \"Herman Melville\",\n            \"title\": \"Moby Dick\",\n            \"isbn\": \"0-553-21311-3\",\n            \"price\": 8.99,\n            \"brand\": {\n                \"version\": \"v1.0.2\"\n            }\n        },\n        {\n            \"category\": \"fiction\",\n            \"author\": \"J. R. R. Tolkien\",\n            \"title\": \"The Lord of the Rings\",\n            \"isbn\": \"0-395-19395-8\",\n            \"price\": 22.99,\n            \"brand\": {\n                \"version\": \"v1.0.3\"\n            }\n        }\n    ],\n    \"bicycle\": {\n        \"color\": \"red\",\n        \"price\": 19.95\n    },\n    \"scores\": {\n        \"math\": {\n            \"score\": 100,\n            \"avg\": 60\n        },\n        \"english\": {\n            \"score\": 95,\n            \"avg\": 80\n        },\n        \"physic\": {\n            \"score\": 90,\n            \"avg\": 70\n        },\n        \"chemistry\": {\n            \"score\": 85,\n            \"avg\": 80\n        },\n        \"chinese\": {\n            \"score\": 60,\n            \"avg\": 75\n        }\n    }\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean2077%2Fjsonpath-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsean2077%2Fjsonpath-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean2077%2Fjsonpath-python/lists"}