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.

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

from natizon import loads

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 = 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 natizon import dumps

data = {
    "package_name": "network_tools",
    "version": "2.1.0",
    "supported_platforms": ["linux", "macos", "windows"],
}

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

Output:

.{
  .package_name = "network_tools",
  .version = "2.1.0",
  .supported_platforms = .{
    "linux",
    "macos",
    "windows",
  },
}

[!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").
• 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.

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 ([] / ()).

from natizon import EmptyContainerMode, loads

data = 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.

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.