Skip to content

v0.4.0 - Cleaner surface, honest abstractions

Choose a tag to compare

View all tags
@ssweber ssweber released this 09 Apr 16:04
· 19 commits to main since this release
v0.4.0
0b672bc
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

pyrung started as a Click PLC simulator, and its early API mirrored Click's flat-memory model. Since then pyrung
has grown past Click — it has @udt, a CircuitPython codegen target, etc — but the API still
carried assumptions from the Click-only days.

v0.4.0 realigns the surface with what pyrung actually is now: a Pythonic ladder DSL with pluggable hardware
backends.

The big shifts

  • PLC replaces PLCRunner and is its own context manager. Enter with PLC(logic) as plc: once and tag
    reads, writes, and assertions all flow through it. The runner.active() dance is gone. Tests shrink by roughly a
    third.

  • Timers and counters are UDTs. Timer and Counter ship in core with .Done and .Acc fields, sized to
    match typical hardware. on_delay(OvenTimer, preset=3000) replaces the two-tag form. This is how Allen-Bradley
    and Siemens have modeled timers since the 80s — pyrung just didn't have UDTs when it started. Click's flat
    T[i]/TD[i] layout falls out for free because the UDT counts match the hardware banks.

  • Time units are IEC-mirror strings. unit="Tms", "Ts", "Tm", "Th", "Td" — matches IEC 61131-3 time
    literals and the T-prefix tag-naming convention without polluting the top-level namespace.

  • Conditions have one way to AND and one way to OR. And(...) and Or(...) replace all_of/any_of; &
    and | are gone, and so is their precedence trap. Comma inside Rung(...) is still implicit AND.

  • Engine and debugger internals moved off the public surface. plc.debug.* for debugger methods,
    underscore-prefixed helpers on Program and TagMap. Autocomplete now shows what users actually need.

  • One validation entry point across dialects. program.validate(dialect="click", tag_map=mapping) and
    program.validate(dialect="circuitpy", hw=hw) use the same plugin mechanism, with per-dialect shortcuts
    delegating to it.

The documentation has been rewritten throughout to match.

Migration: v0.3.x was not API-stable. v0.4.0 is the first release where the API reflects a design I'm
committing to. Future changes will be additive; if anything on this surface needs to change, it'll be deprecated
first, not silently replaced. See the changelog for the full migration checklist.

Test plan

  • make test passes (2000+ tests)
  • make lint clean
  • Docs build without errors
  • Examples run against new API
Assets 4
Loading