rosettakit 0.2.0

Typed Python builders for EDA scripts and command files

RosettaKit

RosettaKit is a small Python library for building typed EDA script documents and rendering them into tool-facing text such as Tcl fragments and command files.

API Stability

RosettaKit 0.2.0 treats the public node, value, document, and builder APIs as stable:

• rosettakit.tcl: Script, TclBuilder, Scalar, PathValue, ListValue, VarRef, Expr, CommandSubstitution, Raw, Condition, Comment, BlankLine, Set, Command, If, RawLine, and helper functions such as word, path, list_value, var, expr, call, raw, and file_isdirectory.
• rosettakit.cmdfile: CommandFile, CommandFileBuilder, ValueType, ValueQuoting, CommandFileDialect, TCL_WORD_DIALECT, PLAIN_DIALECT, Comment, BlankLine, Flag, Option, and RawLine.
• rosettakit.diagnostics.Diagnostic and the exception hierarchy in rosettakit.errors.

Generated text is part of the compatibility surface. Patch releases should not change quoting, indentation, line ordering, or default raw-content policy unless the current output is unsafe or invalid.

RosettaKit only builds script text. It does not parse Tcl, execute EDA tools, manage subprocesses, or model a host workflow.

Tcl API

from rosettakit import tcl

script = tcl.Script()
script.comment("Auto-generated by RosettaKit")
script.set("top_design", tcl.word("gcd_core"))
script.set("clk_freq_mhz", 500)
script.set_path("final_netlist_file", "build out/gcd final.v")
script.set_list("lib_list", ["libs/fast corner.lib", "libs/slow.lib"])
script.set_expr("clk_period_ps", "1000000.0 / $clk_freq_mhz")
script.set_path("tmp_dir", "build out/tmp")
script.file_mkdir(tcl.var("tmp_dir"))

text = script.build()

Use script.validate() to inspect diagnostics before building. Raw Tcl is an explicit escape hatch through tcl.raw(...) or script.raw_line(...); builds fail on raw content unless allow_unsafe_raw=True is passed.

Command File API

from rosettakit import cmdfile

cmd = cmdfile.CommandFile(prefix="-")
cmd.flag("useOpenSTA")
cmd.option("top", "gcd_core")
cmd.option("def", "build out/input.def", value_type=cmdfile.ValueType.PATH)
cmd.options("lef", ["tech/sky130.lef", "macro lef/sram.lef"], value_type=cmdfile.ValueType.PATH)

text = cmd.build()

Command files preserve insertion order, support flags, single options, repeated options, optional omission of empty values, and path-aware quoting. PLAIN_DIALECT emits unquoted whitespace-delimited option values and rejects values that cannot be represented safely in that form.

Examples

The first-party examples use only RosettaKit and Python standard-library modules:

uv run python examples/yosys_global_var.py
uv run python examples/sizer_cmd_file.py
uv run python examples/sizer_env_file.py

They write generated output under ignored paths:

examples/out/yosys/global_var.tcl
examples/out/sizer/design.cmd_file
examples/out/sizer/design.env_file

To verify the generated Tcl with a local Tcl shell:

uv run python examples/yosys_global_var.py
tclsh examples/out/yosys/global_var.tcl

Development

uv sync
uv run pytest
uv run ruff check