Metadata-Version: 2.4
Name: zpl-toolchain
Version: 0.1.7
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Text Processing
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Summary: ZPL II toolchain — parse, validate, format, and print Zebra Programming Language files
Keywords: zpl,zebra,label,printer,parser,printing
License: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/trevordcampbell/zpl-toolchain
Project-URL: Issues, https://github.com/trevordcampbell/zpl-toolchain/issues
Project-URL: Repository, https://github.com/trevordcampbell/zpl-toolchain

# zpl-toolchain

Python bindings for the [zpl-toolchain](https://github.com/trevordcampbell/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](https://pyo3.rs/).

## Installation

```bash
pip install zpl-toolchain
```

## Quick Start

```python
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:

```python
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 = True) -> str` | Send ZPL to a network printer over TCP |
| `query_printer_status` | `(addr: str) -> str` | Query `~HS` host status from a printer |

## Features

- **46 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](https://github.com/trevordcampbell/zpl-toolchain/blob/main/docs/PRINT_CLIENT.md)
- [Diagnostic Codes](https://github.com/trevordcampbell/zpl-toolchain/blob/main/docs/DIAGNOSTIC_CODES.md)
- [GitHub Repository](https://github.com/trevordcampbell/zpl-toolchain)

## Building from Source

```bash
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.

