Core Concepts

Core Concepts

This guide covers the fundamental concepts of PyGo: the .pgo DSL, code generation pipeline, and Go↔Python interop.

The .pgo DSL

PyGo uses a .pgo file as the single source of truth. The DSL is isomorphic to Python — meaning:

• gen_py.py: Generates 1:1 Python code (identical syntax and semantics)
• gen_go.go: Mechanically generates Go code (deterministic translation from AST)

Example .pgo file:

enum Status:
  active
  inactive
  pending

model User:
  id: UUID
  email: Email
  name: String
  status: Status
  tags: Array[String]
  metadata: Map[String]String
  created: DateTime
  updated: DateTime?

handler greet:
  greet(name: String) -> String:
    return f"Hello, {name}!"

route GET /hello/:name -> greet

Code Generation Pipeline

1. Write .pgo file
   ↓
2. Go AST parser builds AST from .pgo
   ↓
3. gen_py.py — 1:1 Python output (gen_py)
   ↓
4. gen_go.go — Mechanical Go output (gen_go, from AST visitor)
   ↓
5. Go runtime serves HTTP via net/http
   ↓
6. Python runtime executes logic via stdlib
   (interoperates via MessagePack + UDS)

gen_py: 1:1 Python Output

The .pgo file uses Python-like syntax. gen_py produces identical Python code — no transformations needed. This means your IDE, linters, and type checkers all work out of the box.

gen_go: Mechanical Go Output

The gen_go step mechanically translates the .pgo AST into Go code using a visitor pattern. This translation is not heuristic — it follows deterministic rules:

PyGo DSL Type	Python Type	Go Type
String	str	string
Int	int	int
Float	float	float64
Bool	bool	bool
UUID	uuid.UUID	string
Email	str (validated)	string
DateTime	datetime	time.Time
URL	str	string
Phone	str	string
Decimal	Decimal	string
Array[T]	list[T]	[]T
Map[K]V	dict[K, V]	map[K]V
Optional[T]	T | None	*T
Enum	enum.Enum	type ... string or int

MessagePack + UDS Interop

The Go runtime and Python runtime communicate via MessagePack over Unix Domain Sockets (UDS):

Go (net/http handler)
  → MessagePack encode
  → Write to UDS socket
  → Python reads from UDS socket
  → MessagePack decode
  → Execute business logic (stdlib only)
  → Return result via UDS → Go → HTTP response

Benefits:

• Performance: Binary protocol, no JSON overhead
• Security: Unix sockets, no network exposure
• Simplicity: Standard Go interface for Python calls

Type System

PyGo extends the type system with compile-time validated types:

PyGo Type	Python Equivalent	Go Equivalent
UUID	uuid.UUID	string
Email	str (validated)	string
DateTime	datetime.datetime	time.Time
Array[T]	list[T]	[]T
Map[K, V]	dict[K, V]	map[K]V
Optional[T]	T | None	*T
Enum	enum.Enum	type ... int/string
URL	str	string
Phone	str	string
Decimal	Decimal	string

Optional Types

PyGo provides explicit nullability handling through the Optional[T] type.

model User:
  name: String
  nickname: String?        # Optional (nullable)
  age: Int?                # Optional (nullable, no default)
  status: String = "active" # Not nullable, has default

• String? — Optional type, can be NULL
• String = "default" — Not nullable, has a default value

File Structure Rules

Extension	Responsibility
.pgo	ONLY business logic (handlers, models, routes)
.html	ONLY views (HTMX templates)
.toml	ONLY config (pygo.toml)

Next Steps

• Architecture Guide
• Installation Guide
• Feature: Enum Types