zpl-toolchain 0.1.4

ZPL II toolchain — parse, validate, format, and print Zebra Programming Language files

zpl-toolchain

Python bindings for the zpl-toolchain — a spec-first, offline, deterministic ZPL II toolchain for parsing, validating, formatting, and printing Zebra Programming Language files.

Built with Rust for performance, exposed to Python via PyO3.

Installation

pip install zpl-toolchain

Quick Start

import json
import zpl_toolchain

# Parse ZPL — returns JSON string with AST + diagnostics
result = json.loads(zpl_toolchain.parse("^XA^FDHello^FS^XZ"))
print(f"Labels: {len(result['ast']['labels'])}")

# Validate ZPL
validation = json.loads(zpl_toolchain.validate("^XA^FDHello^FS^XZ"))
print(f"Valid: {validation['ok']}")

# Format ZPL
formatted = zpl_toolchain.format("^XA^FD Hello ^FS^XZ", "label")
print(formatted)

# Explain a diagnostic code
explanation = zpl_toolchain.explain("ZPL1201")
print(explanation)

Printing

Send ZPL directly to network printers over TCP:

import json
import zpl_toolchain

# Print ZPL to a printer (with optional validation)
result = json.loads(zpl_toolchain.print_zpl(
    "^XA^FDHello^FS^XZ",
    "192.168.1.100",   # printer address (IP or hostname:port)
))
print(f"Success: {result['success']}, Bytes sent: {result['bytes_sent']}")

# Print with profile-based validation
profile_json = open("profiles/zebra-generic-203.json").read()
result = json.loads(zpl_toolchain.print_zpl(
    "^XA^FDHello^FS^XZ",
    "192.168.1.100",
    profile_json,      # optional printer profile for validation
    True,              # validate before sending
))

# Query printer status
status_json = zpl_toolchain.query_printer_status("192.168.1.100")
status = json.loads(status_json)
print(f"Paper out: {status['paper_out']}, Paused: {status['paused']}")

API

All functions return JSON strings — use json.loads() to parse. This gives you zero-dependency interop and full access to the rich structured data.

Core Functions

Function	Signature	Description
parse	(input: str) -> str	Parse ZPL, return AST + diagnostics
parse_with_tables	(input: str, tables_json: str) -> str	Parse with explicit parser tables
validate	(input: str, profile_json: str? = None) -> str	Parse + validate (optional profile)
format	(input: str, indent: str? = None) -> str	Format ZPL ("none", "label", or "field")
explain	(id: str) -> str?	Explain a diagnostic code, or None

Print Functions

Function	Signature	Description
print_zpl	(zpl: str, addr: str, profile: str? = None, validate: bool = False) -> str	Send ZPL to a network printer over TCP
query_printer_status	(addr: str) -> str	Query ~HS host status from a printer

Features

• 45 diagnostic codes covering syntax, semantics, formatting, and preflight checks
• Printer profiles for model-specific validation (label dimensions, DPI, memory limits)
• Deterministic output — identical input always produces identical results
• Spec-driven — parser tables generated from ZPL II command specifications
• Fast — native Rust performance with zero Python runtime overhead

Requirements

• Python 3.9+
• No additional dependencies (self-contained native extension)

Documentation

• Print Client Guide
• Diagnostic Codes
• GitHub Repository

Building from Source

pip install maturin

# Build parser tables first
cargo run -p zpl_toolchain_spec_compiler -- build --spec-dir spec --out-dir generated

# Build and install (development mode)
maturin develop -m crates/python/Cargo.toml

# Or build a wheel
maturin build -m crates/python/Cargo.toml

License

Dual-licensed under MIT or Apache-2.0.