Metadata-Version: 2.4
Name: rosettakit
Version: 0.2.0
Summary: Typed Python builders for EDA scripts and command files
Author: Emin
Author-email: Emin <me@emin.chat>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/Emin017/RosettaKit
Project-URL: Repository, https://github.com/Emin017/RosettaKit
Project-URL: Issues, https://github.com/Emin017/RosettaKit/issues
Description-Content-Type: text/markdown

# 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

```python
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

```python
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:

```bash
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:

```text
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:

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

## Development

```bash
uv sync
uv run pytest
uv run ruff check
```
