README
¶
unagi (鰻)
Compile Python to Go, ship Go to Python.
unagi is a Python compiler with two directions.
unagi build compiles a Python program into readable Go and produces a single static binary, no CPython and no cgo anywhere in the result.
unagi wheel will go the other way, packaging a Go library as a standard Python wheel.
The eel swims both directions.
Status
Pre-alpha, under heavy construction. The current build carries the M0 skeleton: a Python frontend, a boxed object runtime, and a build pipeline that turns a Python file into a running Go binary for a growing subset of the language. Nothing here is ready for real programs yet.
How it works
The compiler parses Python 3.14 source, resolves scopes, and lowers the program onto a Go runtime that mirrors CPython's object semantics: real ints with arbitrary precision to come, ordered dicts, Python truthiness, Python exceptions. Code that type analysis can prove will later lower to plain unboxed Go, with guards that fall back to the boxed path instead of breaking; that mixed-execution design is specified but not built yet. CPython 3.14 is the semantic oracle: where behavior is observable, unagi matches it, and every deliberate divergence is documented.
Try it
go install github.com/tamnd/unagi/cmd/unagi@latest
echo 'print("hello from the eel")' > hello.py
unagi run hello.py
unagi build hello.py -o hello && ./hello
unagi build --emit-go writes the generated Go package out so you can read what your Python became.
License
MIT
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
unagi
command
Command unagi is a Python to Go compiler.
|
Command unagi is a Python to Go compiler. |
|
unagi-conformance
command
Command unagi-conformance drives the differential fixture corpus: run fixtures in golden or live mode, record oracle goldens from the pinned CPython, and report per-band coverage.
|
Command unagi-conformance drives the differential fixture corpus: run fixtures in golden or live mode, record oracle goldens from the pinned CPython, and report per-band coverage. |
|
pkg
|
|
|
build
Package build drives a compile end to end: parse the Python source, emit the Go program, lay out a self-contained Go module next to it, and run the Go toolchain.
|
Package build drives a compile end to end: parse the Python source, emit the Go program, lay out a self-contained Go module next to it, and run the Go toolchain. |
|
cli
Package cli is unagi's command surface: the cobra tree, the global flags, and the fang-rendered help and errors.
|
Package cli is unagi's command surface: the cobra tree, the global flags, and the fang-rendered help and errors. |
|
conformance
The judge: channel-by-channel comparison of two normalized Outcomes.
|
The judge: channel-by-channel comparison of two normalized Outcomes. |
|
emit
Package emit holds the typed lowering paths, the half of the compiler that turns a proven static unit into ordinary Go working on unboxed values.
|
Package emit holds the typed lowering paths, the half of the compiler that turns a proven static unit into ordinary Go working on unboxed values. |
|
floor
Package floor holds the pure-Python standard library floor: the stdlib modules unagi compiles from source as ordinary input rather than backing with Go.
|
Package floor holds the pure-Python standard library floor: the stdlib modules unagi compiles from source as ordinary input rather than backing with Go. |
|
frontend
Package frontend turns Python source into an AST: a lexer that produces the logical token stream (NEWLINE, INDENT, DEDENT and all), a recursive-descent parser over it, and the AST types below.
|
Package frontend turns Python source into an AST: a lexer that produces the logical token stream (NEWLINE, INDENT, DEDENT and all), a recursive-descent parser over it, and the AST types below. |
|
ir
Package ir is the seed of the typed IR pass that doc 15 describes: the layer between the frontend AST and pkg/emit.
|
Package ir is the seed of the typed IR pass that doc 15 describes: the layer between the frontend AST and pkg/emit. |
|
lower
Package lower turns the frontend AST into a Go main package.
|
Package lower turns the frontend AST into a Go main package. |
|
objects
Python function objects and the runtime calling convention.
|
Python function objects and the runtime calling convention. |
|
partition
Package partition decides, for every partition unit, whether it compiles to the native unboxed static tier or runs on the boxed object model, per doc 06.
|
Package partition decides, for every partition unit, whether it compiles to the native unboxed static tier or runs on the boxed object model, per doc 06. |
|
pylexer
Package lexer ports cpython/Parser/lexer/ and cpython/Parser/tokenizer/ to Go.
|
Package lexer ports cpython/Parser/lexer/ and cpython/Parser/tokenizer/ to Go. |
|
pytoken
Package token declares the token kind constants shared by the lexer and tokenize packages.
|
Package token declares the token kind constants shared by the lexer and tokenize packages. |
|
report
Package report is the partitioner's user interface: the per-function build report of doc 06 section 10.
|
Package report is the partitioner's user interface: the per-function build report of doc 06 section 10. |
|
runtime
Package runtime provides the builtin functions and process services that emitted unagi programs call into.
|
Package runtime provides the builtin functions and process services that emitted unagi programs call into. |
|
scratch
Package scratch bounds the disk a test run leaves behind in the system temp directory.
|
Package scratch bounds the disk a test run leaves behind in the system temp directory. |
|
sre
Package sre is the bytecode matcher behind the pure-Python re package.
|
Package sre is the bytecode matcher behind the pure-Python re package. |
|
types
Package types is unagi's type-flow inference lattice, the engine that decides which Python code the compiler may run as native unboxed Go.
|
Package types is unagi's type-flow inference lattice, the engine that decides which Python code the compiler may run as native unboxed Go. |
|
vet
Package vet is unagi's free-threading hazard analyzer.
|
Package vet is unagi's free-threading hazard analyzer. |