v0.1.0 — First real release
A pure-Python binary codec for the AutomationDirect CLICK PLC ladder clipboard format, developed alongside
clicknick and now stable enough to stand on its own. Zero runtime
dependencies, Python 3.11+.
What it does
laddercodec reads and writes the native clipboard binary that CLICK Programming Software uses when you copy and
paste rungs. You can go from a CSV description of a ladder rung to a binary blob ready to paste into Click, or from a
binary blob back to structured Python objects. It also reads Click's internal Scr*.tmp program files via
decode_program().
Encode
encode() accepts a Rung (or a list of them) and produces clipboard binary. All standard instruction types are
supported: contacts (NO, NC, edge, immediate), coils (out, latch, reset, range, oneshot, immediate), comparison
contacts, timers, counters, copy/block-copy/fill, math expressions, shift registers, drum sequencers, flow control,
and Modbus send/receive. Wire topologies, multi-row rungs up to 32 rows, multi-rung buffers, and styled RTF comments
all work. Every supported shape has been verified through a Click paste round-trip, meaning the binary was pasted into
Click and the resulting copy-back matched byte-for-byte.
Decode
decode() reads clipboard binary back into structured data, returning typed instruction objects (not just raw bytes)
for all the same instruction families. decode_program() does the same for Click's program files. Anything the
decoder doesn't recognize comes back as a RawInstruction with the original bytes preserved, so round-trips stay
lossless even for instruction types that haven't been fully modeled yet. A handful of less common types (Email,
Home, Position, Velocity) still surface this way.
CSV I/O
read_csv() and write_csv() convert between the 33-column canonical CSV format and Rung objects. Multi-file
program bundles are supported for projects with multiple screens.
Confidence
615 tests, 41 golden fixtures verified against Click, tested with captures from v2.60 through v3.9x. The binary format
is documented at byte-level detail in the internals docs. This is beta-quality software for a reverse-engineered format, which means it works well for the cases it's been tested against, but there will be edge
cases in the wild that haven't been seen yet.
Links
uv add laddercodec
# or
pip install laddercodec