tessl/pypi-jsonpath-rw

A robust and significantly extended implementation of JSONPath for Python, with a clear AST for metaprogramming.

—

Pending

Overview

Eval results

Files

JSONPath Parsing

Name: tessl/pypi-jsonpath-rw
Author: tessl

Comprehensive parsing functionality that converts JSONPath string expressions into executable Abstract Syntax Tree (AST) objects. The parser supports the full JSONPath syntax with extensions including union operations, filtering, and named operators.

Capabilities

Main Parse Function

The primary entry point for parsing JSONPath expressions from strings into executable objects.

def parse(string):
    """
    Parse a JSONPath string expression into a JSONPath object.
    
    Parameters:
    - string: str, JSONPath expression to parse
    
    Returns:
    JSONPath: Executable JSONPath AST object
    
    Raises:
    Exception: Parse error with location information
    """

Usage Example:

from jsonpath_rw import parse

# Basic field access
expr = parse('$.name')

# Array indexing and field access
expr = parse('users[0].email')

# Wildcard and descendant queries
expr = parse('$..*')

# Complex expressions with filtering
expr = parse('$.users[*] where @.age')

JsonPathParser Class

Advanced parser class providing fine-grained control over the parsing process with debugging capabilities and token stream processing.

class JsonPathParser:
    """
    LALR parser for JSONPath expressions using PLY (Python Lex-Yacc).
    """
    
    def __init__(self, debug=False, lexer_class=None):
        """
        Initialize the parser.
        
        Parameters:
        - debug: bool, enable debugging output
        - lexer_class: class, custom lexer class (default: JsonPathLexer)
        """
    
    def parse(self, string, lexer=None):
        """
        Parse a JSONPath string expression.
        
        Parameters:
        - string: str, JSONPath expression to parse
        - lexer: JsonPathLexer, custom lexer instance
        
        Returns:
        JSONPath: Parsed JSONPath AST object
        """
    
    def parse_token_stream(self, token_iterator, start_symbol='jsonpath'):
        """
        Parse from a token iterator.
        
        Parameters:
        - token_iterator: iterator, token stream
        - start_symbol: str, grammar start symbol
        
        Returns:
        JSONPath: Parsed JSONPath AST object
        """

JsonPathLexer Class

Lexical analyzer that tokenizes JSONPath expressions, handling various string quoting styles and named operators.

class JsonPathLexer:
    """
    Lexical analyzer for JSONPath expressions.
    """
    
    tokens = ['DOUBLEDOT', 'NUMBER', 'ID', 'NAMED_OPERATOR', 'WHERE']
    literals = ['*', '.', '[', ']', '(', ')', '$', ',', ':', '|', '&']
    states = [('singlequote', 'exclusive'), ('doublequote', 'exclusive'), ('backquote', 'exclusive')]
    reserved_words = {'where': 'WHERE'}
    
    def __init__(self, debug=False):
        """
        Initialize the lexer.
        
        Parameters:
        - debug: bool, enable debugging output
        """
    
    def tokenize(self, string):
        """
        Convert string to token iterator.
        
        Parameters:
        - string: str, input string to tokenize
        
        Yields:
        Token objects with type, value, and position information
        
        Raises:
        JsonPathLexerError: Lexical analysis errors
        """

JsonPathLexerError Exception

Exception raised during lexical analysis when invalid characters or syntax are encountered.

class JsonPathLexerError(Exception):
    """
    Exception raised for lexical analysis errors.
    
    Contains detailed error message with line and column information
    to help identify the location of syntax problems in JSONPath expressions.
    
    Raised in the following situations:
    - Unexpected characters in input
    - Unterminated string literals
    - Invalid escape sequences
    - Missing docstrings when using PYTHONOPTIMIZE=2
    """

Supported Syntax

Atomic Expressions

$ - Root object
@ or `this` - Current object
`parent` - Parent object (named operator)
field - Field access
[field] - Bracketed field access
[n] - Array index access

Operators

. - Child access (path1.path2)
.. - Descendant access (path1..path2)
| - Union (path1|path2)
& - Intersection (path1&path2) - Note: Not implemented
where - Filtering (path1 where path2)

Array Operations

[*] - All array elements
[start:end] - Array slice
[start:] - Slice from start
[:end] - Slice to end

Field Operations

* - All fields
field1,field2 - Multiple specific fields
[field1,field2] - Bracketed multiple fields

String Quoting

Fields can be quoted using single quotes, double quotes, or remain unquoted:

field - Unquoted field
'field name' - Single-quoted field
"field name" - Double-quoted field

Error Handling

Parse errors include location information (line and column) to help identify syntax issues:

try:
    expr = parse('$.invalid[syntax')
except Exception as e:
    print(f"Parse error: {e}")
    # Output: Parse error at 1:15 near token syntax (ID)

Install with Tessl CLI