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.

—

Pending

Overview

Eval results

Files

Command Line Interface

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

JSONPath-NG provides a command-line tool for searching JSON files using JSONPath expressions. The tool can process files or read from stdin, making it useful for scripting and data processing pipelines.

Capabilities

Command Line Tool

Execute JSONPath queries from the command line against JSON files or stdin input.

def main(*argv):
    """
    Main CLI function that processes command line arguments and executes JSONPath queries.
    
    Args:
        *argv: Command line arguments (typically sys.argv)
    """

def entry_point():
    """Entry point for the jsonpath_ng console script"""

def find_matches_for_file(expr, f):
    """
    Find JSONPath matches in a JSON file.
    
    Args:
        expr: Parsed JSONPath expression
        f: File object containing JSON data
        
    Returns:
        List of DatumInContext objects with matches
    """

def print_matches(matches):
    """
    Print JSONPath match results to stdout.
    
    Args:
        matches: List of DatumInContext objects
    """

Installation and Usage

The command-line tool is installed automatically with the package:

pip install jsonpath-ng

Usage syntax:

jsonpath_ng EXPRESSION [FILES...]

Command Line Options

EXPRESSION: A JSONPath expression string (required)
FILES: One or more JSON files to search (optional, defaults to stdin)

Usage Examples

Search a single file:

jsonpath_ng '$.users[*].name' data.json

Search multiple files:

jsonpath_ng '$.products[*].price' inventory.json catalog.json

Search from stdin:

cat data.json | jsonpath_ng '$.users[?(@.age > 18)].name'

Using glob patterns:

jsonpath_ng '$.timestamp' logs/*.json

Complex expressions:

# Find all nested email addresses
jsonpath_ng '$..email' contacts.json

# Union of multiple paths
jsonpath_ng '$.users[*].(name|email)' users.json

# Array slicing
jsonpath_ng '$.results[1:5]' results.json

JSONPath Syntax Quick Reference

The CLI tool supports standard JSONPath syntax as implemented by jsonpath-ng:

Atomics:

$ - Root object
`this` - Current object

Operators:

path1.path2 - Child relationship (like XPath /)
path1|path2 - Union of paths
path1..path2 - Recursive descent (somewhere in between)

Fields:

fieldname - Field with specific name
* - Any field
[start:end] - Array slice notation
[*] - Any array index

Output Format

The tool outputs matching values, one per line:

$ echo '{"users": [{"name": "Alice"}, {"name": "Bob"}]}' | jsonpath_ng '$.users[*].name'
Alice
Bob

For complex objects, the entire object is output as JSON:

$ echo '{"users": [{"name": "Alice", "age": 30}]}' | jsonpath_ng '$.users[*]'
{"name": "Alice", "age": 30}

Error Handling

The tool handles common error cases:

Invalid JSONPath syntax: Parser error with helpful message
Invalid JSON files: JSON parsing error
File not found: Standard file system error
No matches: Empty output (no error)

Integration with Shell Pipelines

The CLI tool works well in shell pipelines:

# Count matching results
jsonpath_ng '$.items[*]' data.json | wc -l

# Extract and sort values
jsonpath_ng '$.users[*].name' users.json | sort

# Filter and format results
curl -s api/users | jsonpath_ng '$.data[*].email' | grep "@company.com"

# Pipe to other JSON tools
jsonpath_ng '$.products[*]' catalog.json | jq '.price'

Console Script Registration

The tool is registered as a console script entry point:

# In setup.py
entry_points={
    'console_scripts': [
        'jsonpath_ng=jsonpath_ng.bin.jsonpath:entry_point'
    ],
}

This makes the jsonpath_ng command available system-wide after installation.

Install with Tessl CLI

npx tessl i tessl/pypi-jsonpath-ng

docs