Documentación de milpa

milpa es un microframework de Python 3.14 para construir monolitos modulares, inspirado en la ergonomía de Laravel y la disciplina de capas de Spring. Junta FastAPI (HTTP), Celery (tareas/crons), SQLAlchemy 2.0 (datos) y Typer (consola) detrás de una estructura opinada y un kernel reutilizable.

Esta documentación está pensada para leerse en orden, como la de Laravel: empieza por "Primeros pasos", luego "Conceptos de arquitectura", y profundiza por tema.

Filosofía en una línea: el kernel (milpa/Core) es el framework; lo tuyo vive en app/Modules, app/Models, app/Dictionaries y app/Resources. Tú escribes features; el framework descubre y conecta solo.

Primeros pasos

1. Introducción — qué es milpa y su filosofía.
2. Instalación — uv o pip, drivers de BD.
3. Configuración — .env y la clase Settings.
4. Estructura de directorios — qué hay y dónde.

Conceptos de arquitectura

1. Ciclo de vida de la petición — create_app, lifespan, middlewares, locale.
2. Monolito modular — Core vs Modules, auto-discovery, fronteras.

Lo básico

1. Rutas y controladores — FastAPI por módulo, auto-montaje.
2. Consola (jornal) — comandos, grupos, crear los tuyos.
3. Vistas — Jinja2, namespacing, view().

Profundizando

1. Correo — Mailable, Mailer, drivers, adjuntos, encolado.
2. Colas y tareas — Celery, broker-agnóstico, queue work.
3. Programación de tareas (cron) — @cron_task, schedule run/work.
4. Localización (i18n) — t(), locale ambiente, monolingüe vs i18n.
5. Logging — Loguru, JSON, niveles.
6. Autenticación — validar tokens OAuth2 de Laravel Passport.

Base de datos

1. Configuración del motor — engine agnóstico, DATABASE_URL, zona horaria.
2. Modelos — SQLAlchemy, auto-discovery, mixins (timestamps, soft delete).
3. Repositorios y transacciones — Repository[Model, Id], @transactional.

---

Mapa mental Laravel → milpa

Laravel	milpa
artisan	jornal
php artisan serve	jornal serve
php artisan queue:work	jornal queue work
php artisan schedule:run	jornal schedule run
$schedule->command(...)->everyFiveMinutes()	@cron_task(schedule=every_five_minutes())
Mail::to(...)->send(new X)	Mail.send(X(...), to=[...])
Mailable	Mailable (ABC con build())
Eloquent Model	modelo SQLAlchemy (app/Models)
$table->timestamps()	TimestampMixin
SoftDeletes	SoftDeleteMixin
Repository / Service	Repository[Model, Id] / service @transactional
__('key')	t("key")
config() / .env	settings / .env
Service Provider auto-discovery	auto-discovery por convención (Registry)