Transpiler API

Transpiler API

The PyGo transpiler converts .pgo DSL files into equivalent Python (gen_py) and Go (gen_go) code using a Python AST visitor.

AST Visitor

The transpiler uses Python’s ast module to parse .pgo files into an Abstract Syntax Tree (AST), then walks the tree to generate output code.

Core Classes

ASTVisitor

Base AST visitor class that handles all Python AST node types.

from pygo.transpiler import ASTVisitor

visitor = ASTVisitor()
visitor.visit(ast.parse(source_code))

PyGenerator(ASTVisitor)

Generates 1:1 Python code.

from pygo.transpiler import PyGenerator

gen = PyGenerator()
gen.visit(tree)
output = gen.get_output()

GoGenerator(ASTVisitor)

Mechanically generates Go code.

from pygo.transpiler import GoGenerator

gen = GoGenerator()
gen.visit(tree)
output = gen.get_output()

Supported AST Node Types

The transpiler supports all standard Python AST node types:

Node Type	Description	Go Equivalent
Module	Top-level module	package main
ClassDef	Class definition	type ... struct
FunctionDef	Function definition	func ...
Assign	Assignment	:= or =
If	Conditional	if ... {}
For	For loop	for ... {}
While	While loop	for ... {}
Return	Return statement	return ...
Call	Function call	func(args)
IfExp	Ternary expression	cond ? a : b
ListComp	List comprehension	func() []T { for ... }
DictComp	Dict comprehension	make(map[K]V); for ...

Type Mapping

The transpiler maps Python types to Go types deterministically:

Python / PyGo Type	Go Type
str	string
int	int
float	float64
bool	bool
list[T] / Array[T]	[]T
dict[K, V] / Map[K, V]	map[K]V
UUID	uuid.UUID
Email	string
DateTime	time.Time
Optional[T]	*T
Enum	type ... int

Directives

PyGo-specific transpiler directives can be embedded in .pgo files:

@model

Marks a class for database model generation.

@model
class User:
    name: str
    email: Email

@route

Registers a function as an HTTP handler.

@route("/users")
def list_users():
    return User.all()

@field

Customizes a model field.

@model
class User:
    name: str = field(max_length=100, unique=True)
    email: Email = field(index=True)

Configuration

from pygo.transpiler import Transpiler

transpiler = Transpiler(
    py_output_dir="./pygo_py",
    go_output_dir="./pygo_go",
    verbose=True
)

transpiler.process_file("app.pgo")
transpiler.process_directory("./models")

Plugin System

Custom AST visitors can be registered:

from pygo.transpiler import register_visitor

@register_visitor
class CustomVisitor(ast.NodeVisitor):
    def visit_Call(self, node):
        # Custom handling
        pass

Error Handling

The transpiler raises TranspilerError for unsupported syntax:

try:
    transpiler.process_file("app.pgo")
except TranspilerError as e:
    print(f"Transpiler error at line {e.line}: {e.message}")

CLI Integration

The transpiler is invoked by the CLI:

pygo gen-py app.pgo --output ./pygo_py
pygo gen-go app.pgo --output ./pygo_go
pygo transpile app.pgo --py-output ./pygo_py --go-output ./pygo_go