natizon

natizon is a pure Python parser and serializer for ZON (Zig Object Notation). It converts ZON text directly into standard Python types, and serializes Python objects back into valid ZON — all without intermediate AST objects or wrapper layers. Its API is modeled after the standard library's json module, offering loads() and dumps() as the primary entry points.

Built on Lark, the library handles the full ZON grammar, including structs, arrays, enum literals, multiline strings, hexadecimal and float literals, and quoted identifiers.

API Overview

Full type mapping reference →

Installation

pip install natizon

Or:

uv add natizon

Usage

natizon exposes loads() and dumps() functions that work similarly to the standard library's json module.

Parsing

import natizon

zon_data = r"""
.{
    .package_name = "network_tools",
    .version = "2.1.0",
    .supported_platforms = .{ .linux, .macos, .windows },
    .dependencies = .{
        .lib_a = .{ .url = "https://server.com/a.tar" },
        .lib_b = .{ .path = "../local_b" }
    }
}
"""

# Parses directly into standard Python dicts and lists
parsed_data = natizon.loads(zon_data)

print(parsed_data["package_name"])  # "network_tools"
print(parsed_data["supported_platforms"])  # ["linux", "macos", "windows"]

Serialization

You can serialize standard Python objects back into ZON text using dumps():

from enum import Enum
import natizon


class Difficulty(Enum):
    EASY = "easy"
    HARD = "hard"


game_config = {
    "title": "Neon Dash",
    "difficulty": Difficulty.HARD,
    "player_stats": {"level": 10, "xp": 1500},
}

zon_string = natizon.dumps(game_config, indent=2)
print(zon_string)

Output:

.{
  .title = "Neon Dash",
  .difficulty = .HARD,
  .player_stats = .{
    .level = 10,
    .xp = 1500,
  },
}

Advanced Usage

Validation

dumps() automatically validates your data before serialization. If you need to check whether an object is serializable without triggering the full serialization process, use validate_zon_serializable():

from natizon import validate_zon_serializable

user_settings = {
    "theme": "dark",
    "font_size": 14,
    "notifications": True,
}

# Raises TypeError if the object is not serializable,
# or ValueError if a circular reference is detected.
try:
    validate_zon_serializable(user_settings)
    print("Data is valid!")
except (TypeError, ValueError) as e:
    print(f"Validation failed: {e}")

Custom Serialization

Implement the ZonEncodable protocol on your own classes by defining a to_zon() method that returns a ZonSerializable type:

from dataclasses import dataclass
import natizon
from natizon import ZonSerializable


@dataclass
class ByteSize:
    bytes: int

    def to_zon(self) -> ZonSerializable:
        return f"{self.bytes}B"


data = {
    "cache_limit": ByteSize(1024),
    "buffer_size": ByteSize(2048),
}

zon_string = natizon.dumps(data, indent=2)
print(zon_string)

Output:

.{
  .cache_limit = "1024B",
  .buffer_size = "2048B",
}

License

This project is licensed under the Apache License 2.0. See the LICENSES directory for the full license text.