CSV I/O API

Tier: Stable Core

Read and write Click Ladder CSV files.

laddercodec.read_csv

read_csv(
    path: Path | str, *, strict: bool = True
) -> list[Rung]

Read any Click Ladder CSV and return one Rung per rung.

Handles both single-rung and multi-rung CSV files in a single call. Each Rung is a dataclass with attributes logical_rows, conditions, instructions, comment, comment_rtf::

rungs = read_csv(path)
r = rungs[0]
r.logical_rows    # int
r.conditions      # list[list[ConditionToken]]
r.instructions    # list[AfToken]
r.comment         # str | None

Returns the exact data needed for encode_rung(). Instruction tokens (e.g. X001, out(Y001)) are parsed into Contact / Coil objects; wire tokens remain as strings.

When strict is False, unsupported AF instructions are silently replaced with blank tokens instead of raising.

laddercodec.write_csv

write_csv(
    path: Path | str,
    rungs: list[Rung],
    *,
    index: bool = False,
) -> None

Write decoded rungs to a canonical CSV file.

Parameters

path: Output file path. rungs: One or more decoded rungs (from decode_rung() or decode_rungs()). index: When True, the per-rung R marker is replaced with a 1-based sequential index (R1, R2, R3, ...) counting across the whole file. The default (False) emits a plain R. Indexed files still round-trip through read_csv() — the digits are decorative and ignored on read.

Raises

WriterError If any rung contains unknown instructions that cannot be serialized.