JSONPath RW

A robust and significantly extended implementation of JSONPath for Python, with a clear AST for metaprogramming. This library provides a full language implementation where JSONPath expressions are first-class objects that can be analyzed, transformed, parsed, printed, and extended. It enables powerful JSON data querying with comprehensive path tracking and extension capabilities.

Package Information

• Package Name: jsonpath-rw
• Language: Python
• Installation: pip install jsonpath-rw
• Dependencies: ply, decorator, six

Core Imports

from jsonpath_rw import parse, __version__

For direct expression construction:

from jsonpath_rw.jsonpath import Fields, Slice, Root, Index, DatumInContext

For advanced use cases:

from jsonpath_rw.parser import JsonPathParser
from jsonpath_rw.lexer import JsonPathLexer, JsonPathLexerError
import jsonpath_rw.jsonpath as jsonpath

Basic Usage

from jsonpath_rw import parse

# Parse JSONPath expression
jsonpath_expr = parse('foo[*].baz')

# Find matches in data
data = {'foo': [{'baz': 1}, {'baz': 2}]}
matches = jsonpath_expr.find(data)

# Extract values
values = [match.value for match in matches]  # [1, 2]

# Get full paths
paths = [str(match.full_path) for match in matches]  # ['foo.[0].baz', 'foo.[1].baz']

# Update data
updated_data = jsonpath_expr.update(data, 999)

Architecture

JSONPath RW uses an Abstract Syntax Tree (AST) approach with three main components:

• JSONPath Classes: Base abstract syntax tree nodes representing different path operations
• DatumInContext: Data wrapper that tracks values with their path context and parent relationships
• Parser/Lexer: PLY-based parsing system that converts string expressions to AST objects

This design enables metaprogramming capabilities, allowing JSONPath expressions to be constructed programmatically, analyzed, and transformed while maintaining complete path information for matched data.

Capabilities

JSONPath Parsing

Parse string JSONPath expressions into executable AST objects with comprehensive syntax support including field access, array operations, descendant queries, filtering, and union operations.

def parse(string):
    """
    Parse a JSONPath string expression into a JSONPath object.
    
    Parameters:
    - string: str, JSONPath expression string
    
    Returns:
    JSONPath object that can be used to find/update data
    """

JSONPath Parsing

JSONPath Expression Classes

Core AST node classes representing different JSONPath operations including root access, field selection, array indexing, filtering, descendant queries, and path composition operations.

class JSONPath:
    def find(self, data): ...
    def update(self, data, val): ...
    def child(self, child): ...

class Root(JSONPath): ...
class Fields(JSONPath): ...
class Index(JSONPath): ...
class Slice(JSONPath): ...

JSONPath Expressions

Data Context Management

Wrapper classes that maintain data values along with their path context, enabling full path tracking, parent relationships, and automatic ID field generation for matched data.

class DatumInContext:
    def __init__(self, value, path=None, context=None): ...
    @property
    def full_path(self): ...
    def in_context(self, context, path): ...

class AutoIdForDatum(DatumInContext): ...

Data Context

Command Line Interface

Command-line tool for querying JSON files using JSONPath expressions, supporting both file input and stdin processing with glob pattern matching.

def main(*argv):
    """
    Main CLI function for jsonpath.py command-line tool.
    
    Parameters:
    - argv: Command line arguments [expression, files...]
    """

Command Line Interface

Global Configuration

# Auto ID field configuration
jsonpath.auto_id_field = None  # Default: disabled
jsonpath.auto_id_field = 'id'  # Enable with 'id' field

# Package version
__version__ = '1.4.0'  # Version string constant

When enabled, auto ID field functionality automatically generates path-based identifiers for data elements, useful for tracking objects without explicit ID fields.