Crate kiutils_rs 

kiutils-rs

Pure-Rust, lossless KiCad S-expression document API for agent workflows. Designed for parse -> typed edit -> write with minimal diff noise and explicit forward-compat surfaces.

Why this crate (for AI agents and automation)

Capability	kiutils-rs	Python kiutils	KicadModTree	KiCad IPC Rust API (kicad-api-rs-official)
File round-trip target	First-class (WriteMode::Lossless)	SCM-friendly goal, with known round-trip caveats in docs	Generator-centric (creates footprints; not general file parser API)	Runtime IPC API (different problem)
Unknown/future syntax	Exposed as typed unknown carriers (UnknownNode, UnknownField)	Known issues document format/ordering caveats in some cases	Focused on scripted footprint construction	N/A for S-expression file editing
Architecture for tooling	3 layers (kiutils-sexpr -> kiutils-kicad -> kiutils-rs)	Single Python package/dataclass stack	Tree-based node generator framework	IPC client binding
Public tests/docs signal	Integration tests assert byte-equal lossless writes across formats	Project tests exist; changelog tracks format fixes over time	README/docs emphasize footprint generation workflows	README states docs are not yet available

Source evidence:

• This workspace architecture: https://github.com/Milind220/kiutils-rs/blob/main/README.md
• Lossless/unknown round-trip tests: https://github.com/Milind220/kiutils-rs/blob/main/crates/kiutils_kicad/tests/integration.rs
• Python kiutils known issues: https://github.com/mvnmgrx/kiutils/blob/master/docs/misc/known-issues.rst
• Python kiutils changelog: https://github.com/mvnmgrx/kiutils/blob/master/CHANGELOG.md
• KicadModTree repository README: https://github.com/pointhi/kicad-footprint-generator/blob/master/README.md
• Official KiCad Rust IPC README: https://github.com/Milind220/kicad-api-rs-official/blob/main/README.md

V1 API scope

• .kicad_pcb
• .kicad_mod
• fp-lib-table
• sym-lib-table
• .kicad_dru
• .kicad_pro

Compatibility target:

• Primary: KiCad v10
• Secondary: KiCad v9

Quickstart

use kiutils_rs::{PcbFile, WriteMode};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut doc = PcbFile::read("input.kicad_pcb")?;
    doc.set_generator("kiutils-rs-agent")
        .set_generator_version("0.1.0")
        .upsert_property("Owner", "EDA-Agent");
    doc.write_mode("output.kicad_pcb", WriteMode::Lossless)?;
    Ok(())
}

Crate package name: kiutils-rs Rust import path: kiutils_rs

Structs

DesignRuleSummary

Design-rules (.kicad_dru) APIs.

DesignRulesAst

Design-rules (.kicad_dru) APIs.

DesignRulesDocument

Design-rules (.kicad_dru) APIs.

DesignRulesFile

Design-rules (.kicad_dru) APIs.

Diagnostic

Diagnostics, errors, and write behavior controls.

FootprintAst

Footprint (.kicad_mod) APIs.

FootprintDocument

Footprint (.kicad_mod) APIs.

FootprintFile

Footprint (.kicad_mod) APIs.

FpLibTableFile

Library table (fp-lib-table, sym-lib-table) APIs.

PcbArcSummary

PCB (.kicad_pcb) APIs.

PcbAst

PCB (.kicad_pcb) APIs.

PcbDimensionSummary

PCB (.kicad_pcb) APIs.

PcbDocument

PCB (.kicad_pcb) APIs.

PcbFile

PCB (.kicad_pcb) APIs.

PcbFootprintSummary

PCB (.kicad_pcb) APIs.

PcbGeneratedSummary

PCB (.kicad_pcb) APIs.

PcbGraphicSummary

PCB (.kicad_pcb) APIs.

PcbGroupSummary

PCB (.kicad_pcb) APIs.

PcbLayer

PCB (.kicad_pcb) APIs.

PcbNet

PCB (.kicad_pcb) APIs.

PcbProperty

PCB (.kicad_pcb) APIs.

PcbSegmentSummary

PCB (.kicad_pcb) APIs.

PcbSetupSummary

PCB (.kicad_pcb) APIs.

PcbTargetSummary

PCB (.kicad_pcb) APIs.

PcbViaSummary

PCB (.kicad_pcb) APIs.

PcbZoneSummary

PCB (.kicad_pcb) APIs.

ProjectAst

Project (.kicad_pro) APIs.

ProjectDocument

Project (.kicad_pro) APIs.

ProjectFile

Project (.kicad_pro) APIs.

Span

Diagnostics, errors, and write behavior controls.

SymLibTableFile

Library table (fp-lib-table, sym-lib-table) APIs.

UnknownField

Diagnostics, errors, and write behavior controls.

UnknownNode

Diagnostics, errors, and write behavior controls.

VersionPolicy

Diagnostics, errors, and write behavior controls.

Enums

Error

Diagnostics, errors, and write behavior controls.

KiCadSeries

Diagnostics, errors, and write behavior controls.

Severity

Diagnostics, errors, and write behavior controls.

WriteMode

Diagnostics, errors, and write behavior controls.

Type Aliases

FpLibTableAst

Library table (fp-lib-table, sym-lib-table) APIs.

FpLibTableDocument

Library table (fp-lib-table, sym-lib-table) APIs.

ProjectExtra

Project (.kicad_pro) APIs.

SymLibTableAst

Library table (fp-lib-table, sym-lib-table) APIs.

SymLibTableDocument

Library table (fp-lib-table, sym-lib-table) APIs.