Conceptos Clave

Conceptos Clave

Esta guía cubre los conceptos fundamentales de PyGo: el DSL .pgo, el pipeline de generación de código e la inter-operabilidad Go↔Python.

El DSL .pgo

PyGo usa un archivo .pgo como única fuente de verdad. El DSL es isomórfico a Python — lo que significa:

• gen_py.py: Genera código Python 1:1 (sintaxis e semántica idénticas)
• gen_go.go: Genera mecánicamente código Go (determinista desde AST)

Ejemplo de archivo .pgo:

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

Pipeline de Generación de Código

1. Escribir archivo .pgo
   ↓
2. Parser AST en Go construye AST desde .pgo
   ↓
3. gen_py.py — salida Python 1:1 (gen_py)
   ↓
4. gen_go.go — salida Go mecánica (gen_go, desde AST visitor)
   ↓
5. Runtime Go sirve HTTP vía net/http
   ↓
6. Runtime Python ejecuta lógica vía stdlib
   (interoperan vía MessagePack + UDS)

gen_py: Salida Python 1:1

El archivo .pgo usa sintaxis similar a Python. gen_py produce código Python idéntico — sin transformaciones necesarias. Esto significa que tu IDE, linters y verificadores de tipos funcionan de inmediato.

gen_go: Salida Go Mecánica

El paso gen_go traduce mecánicamente el AST .pgo a código Go usando el patrón visitor. Esta traducción no es heurística — sigue reglas deterministas:

Tipo PyGo DSL	Tipo Python	Tipo Go
String	str	string
Int	int	int
Float	float	float64
Bool	bool	bool
UUID	uuid.UUID	string
Email	str (validado)	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 ... int/string

MessagePack + UDS Inter-operabilidad

El runtime Go y el runtime Python se comunican vía MessagePack sobre Sockets de Dominio Unix (UDS):

Go (handler de net/http)
  → Codificar MessagePack
  → Escribir al socket UDS
  → Python lee del socket UDS
  → Decodificar MessagePack
  → Ejecutar lógica de negocio (stdlib únicamente)
  → Devolver resultado vía UDS → Go → respuesta HTTP

Beneficios:

• Rendimiento: Protocolo binario, sin overhead JSON
• Seguridad: Sockets Unix, sin exposición de red
• Simplicidad: Interfaz estándar de Go para llamadas a Python

Sistema de Tipos

PyGo extiende el sistema de tipos con tipos validados en tiempo de compilación:

Tipo PyGo	Equivalente Python	Equivalente Go
UUID	uuid.UUID	string
Email	str (validado)	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

Tipos Opcionales (Optional)

PyGo proporciona manejo explícito de nulidad a través del tipo Optional[T].

model User:
  name: String
  nickname: String?        # Optional (nullable)
  age: Int?                # Optional (nullable, sin valor por defecto)
  status: String = "active" # No nulable, tiene valor por defecto

• String? — Tipo opcional, puede ser NULL
• String = "default" — No nulable, tiene valor por defecto

Reglas de Estructura de Archivos

Extensión	Responsabilidad
.pgo	SOLO lógica de negocio (handlers, modelos, rutas)
.html	SOLO vistas (plantillas HTMX)
.toml	SOLO config (pygo.toml)

Próximos Pasos

• Guía de Arquitectura
• Instalación
• Característica: Enum Types