natizon

natizon (short for "native-ZON") is a pure Python parser and serializer for ZON (Zig Object Notation). Built on top of Lark, it provides a familiar, json-like interface for decoding ZON strings directly into Python data structures, and for encoding Python data structures back into ZON text. It relies strictly on standard Python types, without AST wrappers and so on.

[!NOTE] natizon is slightly more lenient than the official std.zon parser. This flexibility is intentional, making it easier to consume and work with data in Python environments.

For example, you can safely parse ZON containing unquoted keywords like if or fn, but dumps() will always normalize these to .@"if" and .@"fn" to guarantee strict compatibility.

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.

[!TIP] Looking to parse build.zig.zon?

Check out this Python script for Parsing and validating build.zig.zon to see how to:

• load Zig 0.16 package metadata using natizon,
• validate fields with Pydantic,
• and print a pretty JSON dump using Rich.

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,
  },
}

[!NOTE] While loads() and dumps() are designed to be compatible, some ZON-specific constructs do not roundtrip exactly:

• Enum literals (e.g., .linux) are parsed into Python strings and will serialize back as quoted strings ("linux"). If you want to preserve them as ZON Enum literals, convert them to your Enum subclass member (e.g.,Color.RED) instead.
• Enum flags (enum.Flag, enum.IntFlag) are not serializable, as their bitwise nature lacks a canonical ZON representation. To include them in your output, convert them to a standard Enum tag, integer, or array first.
• Char literals (e.g., 'a') are parsed into Python integers and will serialize back as integers (97).
• Empty arrays ([]) serialize to .{}, which loads() parses as an empty dict by default. Use EmptyContainerMode.SEQUENCE if you need them to parse back as lists/tuples.

Advanced Usage

Validation

dumps() automatically validates your data before serialization. However, if you need to check if an object is serializable without triggering the full serialization process, you can 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

If you have custom classes that you want to serialize into ZON, you can implement the ZonEncodable protocol. Simply define 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",
}

[!IMPORTANT] If an object implements the ZonEncodable protocol, dumps() always prefers its to_zon() method over any built-in serialization of the object’s actual type. This means a subclass of str, int, or Enum that defines to_zon() will be serialized as whatever to_zon() returns, not as a string, integer, or enum literal.

ZON to Python Type Mapping

When you pass a ZON string to natizon.loads(), the parser automatically converts ZON primitives and structures into their closest Python types.

Here's breakdown:

Primitives and Literals

Structures and Containers

Configuration

• use_tuples (bool, default False): If True, parses ZON arrays (e.g., .{ 1, 2, 3 }) as Python tuples instead of lists.
• empty_mode (EmptyContainerMode, default EmptyContainerMode.DICT): Controls whether an empty container .{} becomes an empty dictionary ({}) or an empty sequence ([] / ()).

import natizon
from natizon import EmptyContainerMode

data = natizon.loads(
    ".{}",
    use_tuples=True,
    empty_mode=EmptyContainerMode.SEQUENCE,
)
print(data)  # Output: ()

Python to ZON Type Mapping

When you pass a Python object to natizon.dumps(), it is converted to its natural ZON representation.

Note: For Mapping types, only string keys are supported. Non-string keys will result in a TypeError.

Configuration

• indent (int | str | None, default None): If a non-negative integer, indents with that many spaces per level. If a string (like "\t"), uses that string to indent each level. If None, outputs a compact, single-line representation.
• sort_keys (bool, default False): If True, dictionary keys are output in sorted order.

License

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