or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

command-line.mdcore-parsing.mdextensions.mdindex.mdpath-operations.md
tile.json

tessl/pypi-jsonpath-ng

A final implementation of JSONPath for Python that aims to be standard compliant, including arithmetic and binary comparison operators and providing clear AST for metaprogramming.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/jsonpath-ng@1.7.x

To install, run

npx @tessl/cli install tessl/pypi-jsonpath-ng@1.7.0

index.mddocs/

JSONPath-NG

A final implementation of JSONPath for Python that aims to be standard compliant, including arithmetic and binary comparison operators and providing clear AST for metaprogramming. JSONPath-NG provides a robust and significantly extended implementation of JSONPath for Python, treating JSONPath expressions as first-class objects that are easy to analyze, transform, parse, print, and extend.

Package Information

  • Package Name: jsonpath-ng
  • Language: Python
  • Installation: pip install jsonpath-ng

Core Imports

Basic JSONPath functionality:

from jsonpath_ng import jsonpath, parse

Extended functionality with arithmetic and filtering:

from jsonpath_ng.ext import parse

Programmatic JSONPath construction:

from jsonpath_ng.jsonpath import (
    Root, This, Fields, Index, Slice, Child, 
    Where, WhereNot, Descendants, Union, Parent
)

Basic Usage

from jsonpath_ng import parse

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

# Sample data
data = {'foo': [{'baz': 1}, {'baz': 2}]}

# Find matching values
matches = jsonpath_expr.find(data)
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 matching values
updated_data = jsonpath_expr.update(data, 42)
# Result: {'foo': [{'baz': 42}, {'baz': 42}]}

# Filter out matching values
filtered_data = jsonpath_expr.filter(lambda x: x == 2, data)
# Result: {'foo': [{'baz': 1}, {}]}

Architecture

JSONPath-NG is built around a comprehensive AST (Abstract Syntax Tree) model:

  • JSONPath: Base class for all JSONPath expressions with core operations (find, update, filter)
  • DatumInContext: Wrapper preserving path information and context for located data
  • Expression Classes: Each JSONPath syntax element has a corresponding class (Root, This, Fields, etc.)
  • Parser: Converts string expressions into JSONPath AST objects
  • Extensions: Additional functionality for arithmetic, filtering, and string operations

This design enables programmatic JSONPath construction, AST manipulation, and extensible functionality while maintaining full compatibility with standard JSONPath syntax.

Capabilities

Core Parsing and Expression Building

Parse JSONPath expressions from strings or build them programmatically using the AST classes. Supports standard JSONPath syntax with extensions for arithmetic and comparison operations.

def parse(string: str) -> JSONPath: ...
class Root(JSONPath):
    def find(self, data) -> List[DatumInContext]: ...
    def update(self, data, val): ...
    def filter(self, fn, data): ...

class This(JSONPath):
    def find(self, datum) -> List[DatumInContext]: ...
    def update(self, data, val): ...
    def filter(self, fn, data): ...

class Fields(JSONPath):
    def __init__(self, *fields: str): ...
    def find(self, datum) -> List[DatumInContext]: ...
    def update(self, data, val): ...
    def filter(self, fn, data): ...

Core Parsing and Expression Building

Path Operations

Core operations for finding, updating, and filtering data using JSONPath expressions. Includes context preservation and full path tracking.

class JSONPath:
    def find(self, data) -> List[DatumInContext]: ...
    def find_or_create(self, data) -> List[DatumInContext]: ...
    def update(self, data, val): ...
    def update_or_create(self, data, val): ...
    def filter(self, fn, data): ...

class DatumInContext:
    def __init__(self, value, path=None, context=None): ...
    @property
    def full_path(self) -> JSONPath: ...
    @property
    def id_pseudopath(self) -> JSONPath: ...

Path Operations

Extensions

Extended JSONPath functionality including arithmetic operations, advanced filtering with comparison operators, string manipulation functions, and iterable operations like length and sorting.

# From jsonpath_ng.ext
def parse(path: str, debug: bool = False) -> JSONPath: ...
# Arithmetic operations
class Operation(JSONPath):
    def __init__(self, left, op: str, right): ...
    def find(self, datum) -> List[DatumInContext]: ...

# Filtering operations  
class Filter(JSONPath):
    def __init__(self, expressions): ...
    def find(self, datum) -> List[DatumInContext]: ...

Extensions

Command Line Interface

Command-line tool for executing JSONPath queries against JSON files or stdin input. Supports all JSONPath syntax and integrates well with shell pipelines.

def main(*argv): ...
def entry_point(): ...
def find_matches_for_file(expr, f): ...
def print_matches(matches): ...

Command Line Interface

Types

class JSONPath:
    """Base class for JSONPath abstract syntax"""
    def find(self, data) -> Iterable[DatumInContext]: ...
    def find_or_create(self, data) -> Iterable[DatumInContext]: ...
    def update(self, data, val): ...  # val can be value or callable(old, parent, key) -> new
    def update_or_create(self, data, val): ...  # val can be value or callable(old, parent, key) -> new
    def filter(self, fn, data): ...  # fn: callable(value) -> bool
    def child(self, child: 'JSONPath') -> 'JSONPath': ...
    def make_datum(self, value) -> DatumInContext: ...

class DatumInContext:
    """Represents a datum along a path from a context"""
    def __init__(self, value, path: JSONPath = None, context: 'DatumInContext' = None): ...
    @classmethod
    def wrap(cls, data) -> 'DatumInContext': ...
    def in_context(self, context, path) -> 'DatumInContext': ...
    @property
    def full_path(self) -> JSONPath: ...
    @property
    def id_pseudopath(self) -> JSONPath: ...
    value: Any
    path: JSONPath
    context: 'DatumInContext'

Exceptions

class JSONPathError(Exception):
    """Base exception for all JSONPath operations"""

class JsonPathLexerError(JSONPathError):
    """Raised when the lexer encounters invalid tokens during tokenization"""

class JsonPathParserError(JSONPathError):
    """Raised when the parser encounters invalid JSONPath syntax"""

Global Configuration

# Module-level configuration
jsonpath.auto_id_field: Optional[str] = None  # Enable automatic ID field generation

# Module-level constants
__version__: str = "1.7.0"  # Package version
NOT_SET: object  # Sentinel value for missing data  
LIST_KEY: object  # Special key used for internal list operations