{"id":523,"library":"jsonpath-ng","title":"JSONPath-NG","description":"jsonpath-ng is a robust and significantly extended implementation of JSONPath for Python. It aims to be standard compliant, including arithmetic and binary comparison operators, and provides a clear Abstract Syntax Tree (AST) for metaprogramming. As of version 1.8.0, it is actively maintained with a regular release cadence, merging functionalities from older libraries like jsonpath-rw and jsonpath-rw-ext.","status":"active","version":"1.8.0","language":"python","source_language":"en","source_url":"https://github.com/h2non/jsonpath-ng","tags":["json","jsonpath","data-query","parsing","ast","extractor"],"install":[{"cmd":"pip install jsonpath-ng","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The core `parse` function for standard JSONPath is directly available from `jsonpath_ng`. Use `jsonpath_ng.ext.parse` only for extended features if explicitly needed.","wrong":"from jsonpath_ng.ext import parse","symbol":"parse","correct":"from jsonpath_ng import parse"},{"note":"Provides programmatic construction of JSONPath expressions without string parsing, though `parse` is more commonly used for string expressions.","symbol":"jsonpath","correct":"from jsonpath_ng import jsonpath"}],"quickstart":{"code":"from jsonpath_ng import jsonpath, parse\nimport json\n\ndata = {\n    \"store\": {\n        \"book\": [\n            {\"category\": \"reference\", \"author\": \"Nigel Rees\", \"title\": \"Sayings of the Century\", \"price\": 8.95},\n            {\"category\": \"fiction\", \"author\": \"Evelyn Waugh\", \"title\": \"Sword of Honour\", \"price\": 12.99},\n            {\"category\": \"fiction\", \"author\": \"Herman Melville\", \"title\": \"Moby Dick\", \"isbn\": \"0-553-21311-3\", \"price\": 8.99},\n            {\"category\": \"fiction\", \"author\": \"J.R.R. Tolkien\", \"title\": \"The Lord of the Rings\", \"isbn\": \"0-395-19395-8\", \"price\": 22.99}\n        ],\n        \"bicycle\": {\"color\": \"red\", \"price\": 19.95}\n    },\n    \"expensive\": 10\n}\n\n# Find all book titles\njsonpath_expr = parse('$.store.book[*].title')\nmatches = jsonpath_expr.find(data)\nbook_titles = [match.value for match in matches]\nprint(f\"Book Titles: {book_titles}\")\n\n# Find books cheaper than $10\njsonpath_expr = parse('$.store.book[?(@.price < 10)].title')\nmatches = jsonpath_expr.find(data)\ncheap_books = [match.value for match in matches]\nprint(f\"Cheap Books (titles): {cheap_books}\")\n\n# Update a value (e.g., change bicycle color)\nupdate_expr = parse('$.store.bicycle.color')\nupdated_data = update_expr.update(data, 'blue')\nprint(f\"Updated Bicycle Color: {updated_data['store']['bicycle']['color']}\")","lang":"python","description":"This quickstart demonstrates how to parse JSON data, extract specific elements using JSONPath expressions, filter results, and update values within a JSON structure. It covers the core `parse` and `find` methods, as well as a basic `update` operation."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"Python 3.7 support was removed in v1.7.0. Python 3.8 and 3.9 support were removed in v1.8.0. Users on these Python versions must upgrade to Python 3.10 or newer to use jsonpath-ng >= 1.8.0.","severity":"breaking","affected_versions":">=1.7.0 (for 3.7), >=1.8.0 (for 3.8, 3.9)"},{"fix":"Always check if the `matches` list is not empty (e.g., `if matches: value = matches[0].value`) or use a list comprehension if expecting multiple results.","message":"The `find()` method returns a list of `DatumInContext` objects, even if only one or no matches are found. Users commonly forget to check if the list is empty before accessing `[0].value`, leading to an `IndexError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to the latest version of `jsonpath-ng` to benefit from these fixes, especially if performing `update` operations on data that might contain `None` or boolean values.","message":"In older versions, updating a JSON object using `jsonpath_expr.update()` could fail with `TypeError` if the target value was `None` or a boolean. While fixes have been implemented (e.g., for boolean values in v1.7.0, and null values in earlier patches), ensure you are on a recent version if experiencing such issues.","severity":"gotcha","affected_versions":"<1.7.0 (for boolean), pre-v1.0.0 (for null)"},{"fix":"Use `this` (e.g., `[?(this.price < 10)]`) instead of `@` when referencing the current object within filter expressions.","message":"The library internally uses `this` to refer to the 'current object' within a filter expression, rather than the `@` symbol often seen in other JSONPath implementations. While `@` might work in simple cases due to parsing ambiguities, `this` is the explicit and recommended syntax for clarity and correctness.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:38:10.462Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Ensure the library is installed using pip: `pip install jsonpath-ng`","cause":"The `jsonpath-ng` library is not installed or is not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'jsonpath_ng'"},{"fix":"For extended filter syntax and other advanced features, import `parse` from `jsonpath_ng.ext` instead: `from jsonpath_ng.ext import parse`","cause":"This error often occurs when using filter expressions `[?()]` with the default `jsonpath_ng.parse` function, which might not fully support advanced filter syntax from other JSONPath implementations.","error":"jsonpath_ng.exceptions.JsonPathLexerError: Error on line 1, col X: Unexpected character: ?"},{"fix":"Access string keys that look like numbers using bracket notation with quotes: `jsonpath_expr = parse('$.data[\"1\"]')`","cause":"This error typically occurs when attempting to access a dictionary key that is a string containing only digits using dot notation (e.g., `$.data.1`), as `jsonpath-ng` interprets it as a numerical index.","error":"jsonpath_ng.exceptions.JsonPathParserError: Parse error at X:Y near token Z (NUMBER)"},{"fix":"To get the key, you need to access it from the `path` attribute of the `DatumInContext` object, typically by checking if the path is a `Child` or `Fields` instance and extracting its `field_name`: `[match.path.field_name for match in jsonpath_expr.find(data) if isinstance(match.path, (jsonpath_ng.jsonpath.Child, jsonpath_ng.jsonpath.Fields))]`","cause":"The `DatumInContext` object returned by `find()` in `jsonpath-ng` does not have a direct `key` attribute to retrieve the key of the matched element; it primarily provides `value`, `path`, and `context`.","error":"AttributeError: 'DatumInContext' object has no attribute 'key'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.2,"disk_size":"18.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.2,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":2.8,"disk_size":"20.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.8,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":2.7,"disk_size":"12.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":2.7,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"11.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.7,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.2,"disk_size":"17.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.2,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}