json

import json

The json module wraps vendored cJSON. json.Value is an opaque managed handle over a cJSON tree.

Parsing and serializing a json.Value

Signature	Description
json.parse(text: str) -> json.Value	Parse JSON string into a json.Value tree
json.stringify(value: json.Value) -> str	Serialize a json.Value to a JSON string

Type checks

Signature	Description
json.is_null(value: json.Value) -> bool
json.is_bool(value: json.Value) -> bool
json.is_number(value: json.Value) -> bool
json.is_string(value: json.Value) -> bool
json.is_array(value: json.Value) -> bool
json.is_object(value: json.Value) -> bool

Value extraction

Signature	Description
json.as_bool(value: json.Value) -> bool
json.as_float(value: json.Value) -> float
json.as_string(value: json.Value) -> str

Object and array access

Signature	Description
json.len(value: json.Value) -> int	Array or object size
json.has(value: json.Value, key: str) -> bool	Object key existence
json.keys(value: json.Value) -> list[str]	Object keys
json.values(value: json.Value) -> list[json.Value]	Object or array values
json.items(value: json.Value) -> list[(str, json.Value)]	Object key-value pairs
json.get(value: json.Value, key: str) -> json.Value	Get by key (JSON null if missing)
json.get_or(value: json.Value, key: str, fallback: json.Value) -> json.Value	Get with fallback
json.get_index(value: json.Value, index: int) -> json.Value	Get array element by index

Low-level example

import json

root = json.parse("{\"n\":\"py4\",\"a\":true,\"s\":3.5,\"t\":[\"c\",\"p\"]}")

assert json.is_object(root)
assert json.is_string(json.get(root, "n"))

print(json.as_string(json.get(root, "n")))    # py4
print(json.as_bool(json.get(root, "a")))      # True
print(json.as_float(json.get(root, "s")))     # 3.5
print(json.len(json.get(root, "t")))          # 2
print(json.keys(root))
print(json.stringify(root))

Typed deserialization — json.from_string[Type]

json.from_string[Type](text) is a compiler built-in that generates a typed deserializer. It is not a native function declared in json.p4.

import json

class Meta:
    label: str

class User:
    name: str
    tags: list[str]
    meta: Meta | None

user = json.from_string[User]("{\"name\":\"ann\",\"tags\":[\"x\"],\"meta\":{\"label\":\"core\"}}")
print(user)

Supported types for from_string: int, float, bool, str, tuples, list[...], dict[str, ...], classes, T | None.

users  = json.from_string[list[User]]("[{\"name\":\"ann\",\"age\":3}]")
pair   = json.from_string[(str, int)]("[\"team\",2]")
scores = json.from_string[dict[str, int]]("{\"a\":1,\"b\":2}")
maybe  = json.from_string[str | None]("null")

Typed serialization — json.to_string

json.to_string(value) is also a compiler built-in that serializes any supported typed value to a JSON string.

import json

class User:
    name: str
    tags: list[str]

user = User("ann", ["x", "y"])
print(json.to_string(user))

users: list[User] = [User("ann", []), User("bob", ["x"])]
print(json.to_string(users))

Supported types for to_string: same as from_string, plus json.Value (where it behaves like json.stringify).