pygjson

PYGJSON is a Python binding for tidwall/gjson.rs - fast JSON path queries.

The original GJSON: tidwall/gjson

Installation

pip install pygjson

Quick example

import pygjson

JSON = """{
  "name": {"first": "Tom", "last": "Anderson"},
  "age": 37,
  "children": ["Sara", "Alex", "Jack"],
  "friends": [
    {"first": "Dale",  "last": "Murphy", "age": 44},
    {"first": "Roger", "last": "Craig",  "age": 68},
    {"first": "Jane",  "last": "Murphy", "age": 47}
  ]
}"""

str(pygjson.get(JSON, "name.last"))                           # 'Anderson'
int(pygjson.get(JSON, "age"))                                 # 37
int(pygjson.get(JSON, "children.#"))                         # 3
str(pygjson.get(JSON, "children.1"))                          # 'Alex'
str(pygjson.get(JSON, 'friends.#(last="Murphy").first'))      # 'Dale'

[str(r) for r in pygjson.get(JSON, "children|@reverse")]
# ['Jack', 'Alex', 'Sara']

pygjson.validate(JSON)  # True

p = pygjson.compile("name.first")
str(pygjson.get(JSON, p))  # 'Tom'  — reuse the compiled path

API

Module-level functions

get_bytes and get_many_bytes raise UnicodeDecodeError if json is not valid UTF-8.

All query functions (get, get_bytes, get_many, get_many_bytes) and Result.get / Result.get_many accept either a plain str or a compiled Path as the path argument.

Queries are zero-copy: a Result borrows the buffer of the source str / bytes object (keeping it alive via a reference) instead of copying the document, so holding many Results from the same document costs no extra memory. Queries on documents ≥ 32 KiB release the GIL, so concurrent queries from multiple threads run in parallel.

Path

compile(path) parses a path string once and returns a Path object that can be reused across multiple queries. Pass a Path anywhere a path string is accepted.

Result

get and parse return a Result. Result accessors

Properties

gjson-native methods — mirror the Rust gjson::Value API:

Pythonic methods — follow standard Python protocols:

Lazy iteration

iter(r), r.keys(), r.values() and r.items() all return lightweight lazy objects rather than fully-materialised lists, mirroring Python's built-in dict_keys / dict_values / dict_items.

r = parse('{"a": 1, "b": 2, "c": 3}')

ks = r.keys()           # KeysView — no materialisation yet
len(ks)                 # 3
"a" in ks               # True
list(ks)                # ['a', 'b', 'c']

for k, child in r.items():   # ItemsView, lazily yields one pair at a time
    ...

If you need a fully materialised collection, wrap the view with list(...) or dict(...) explicitly, or use r.value to get a native Python object.

Usage examples

from pygjson import compile, get, get_bytes, get_many, get_many_bytes, parse, validate

# Missing value returns Result(exists=False)
r = get(JSON, "no.such.path")
r.exists()   # False
bool(r)      # False (null → bool(None) = False)

# Type conversion
age = get(JSON, "age")
age.to_int()    # gjson i64/u64 behaviour
int(age)        # Python int protocol
age.type_       # <class 'int'>
age.value       # 37

# Boolean distinction
get('{"flag": true}', "flag").to_bool()   # True  (JSON true literal)
bool(get(JSON, "age"))                    # True  (37 is truthy)
bool(get('{"n": 0}', "n"))               # False (0 is falsy)

# Bytes input
get_bytes(JSON.encode(), "name.first")    # Result("Tom")

# Array iteration and subscript
children = get(JSON, "children")
list(children)                  # [Result("Sara"), Result("Alex"), Result("Jack")]
[str(r) for r in children]      # ['Sara', 'Alex', 'Jack']
"Sara" in children              # True
str(children[0])                # 'Sara'
str(children[-1])               # 'Jack'
[str(r) for r in children[1:]] # ['Alex', 'Jack']

# String subscript
first = get(JSON, "name.first")   # "Tom"
first[0]                          # 'T'
first[-1]                         # 'm'
first[1:]                         # 'om'
first[::-1]                       # 'moT'

# Object (dict-like) access
name = get(JSON, "name")
str(name["first"])              # 'Tom'
"first" in name                 # True
list(name)                      # ['first', 'last']  — keys
dict(name)                      # {'first': Result("Tom"), 'last': Result("Anderson")}
for k, v in name.items():
    print(k, str(v))

# repr
repr(name)                      # '<Result type=dict, keys=["first", "last"]>'
repr(children)                  # '<Result type=list, value=["Sara", "Alex", ...]>'
repr(age)                       # '37'
repr(first)                     # 'Tom'

# Chained queries
parse(JSON).get("name").get("first")   # Result("Tom")

# Fetch multiple paths in one call
get_many(JSON, ["name.first", "age", "children.1"])
# [Result(Tom), Result(37), Result(Alex)]

# Missing paths return Result(exists=False)
get_many(JSON, ["name.first", "no.such.path"])
# [Result(Tom), Result()]

# get_many with bytes input
get_many_bytes(JSON.encode(), ["name.first", "age"])
# [Result(Tom), Result(37)]

# Result.get_many for sub-queries relative to a parsed document
parse(JSON).get_many(["name.first", "name.last"])
# [Result(Tom), Result(Anderson)]

# Pre-compile a path for reuse across multiple queries
p = compile("name.first")
get(JSON, p)                    # Result(Tom)
get_bytes(JSON.encode(), p)     # Result(Tom)

# Compiled paths work with get_many / get_many_bytes
paths = [compile("name.first"), compile("age"), compile("children.1")]
get_many(JSON, paths)
# [Result(Tom), Result(37), Result(Alex)]

# Compiled paths work with Result.get / Result.get_many
root = parse(JSON)
root.get(compile("name.first"))
# Result(Tom)
root.get_many([compile("name.first"), compile("name.last")])
# [Result(Tom), Result(Anderson)]

Path syntax

For the full path / query / modifier syntax see the upstream gjson.rs and the original GJSON path syntax.

License

MIT