Documentación de tequio

tequio es la extracción worker-side de milpa: un núcleo de Python 3.14 para servicios que NO sirven HTTP —daemons, pipelines de datos, monitores, ETLs, cron-jobs— con el mismo estilo y buena parte del mismo kernel. Junta 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 "Arquitectura", y profundiza por tema.

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

¿tequio o milpa?

Si tu servicio sirve páginas o API REST, quieres milpa (trae Http, Auth, Views/Vite e i18n de la UI además de todo lo de tequio). Si solo procesa trabajo en background contra una base de datos, tequio te deja más ligero — con correo incluido, porque vuelve al worker. A lo largo de estas docs, lo que vive en milpa y no aquí se anota con un "esto vive en milpa" y su enlace.

Primeros pasos

1. Introducción — qué es tequio, su filosofía y qué se quedó en milpa.
2. Instalación — uv o pip, drivers de BD, broker.
3. Configuración — .env y la clase Settings.
4. Estructura de directorios — qué hay y dónde.
5. Ciclo de vida — arranque de la consola, Celery y el discovery.

Arquitectura

1. Monolito modular — Core vs Modules, auto-discovery, fronteras (import-linter).
2. Errores de dominio — DomainError y el borde de error del CLI.

Consola

1. jornal — comandos, grupos, crear los tuyos.

Base de datos

1. Base de datos — engine agnóstico, DATABASE_URL, zona horaria, migraciones Alembic.
2. Modelos — SQLAlchemy, auto-discovery, mixins (timestamps, soft delete).
3. Repositorios y transacciones — Repository[Model, Id], @transactional.
4. Filtrado y paginación — DSL de filtrado + paginación.

Background

1. Jobs (@job) — background on-demand, .dispatch(), broker_guard.
2. Colas y tareas — Celery, broker-agnóstico, queue work.
3. Programación (cron) — @cron_task, schedule run/work.

Patrones (estilo milpa)

1. Eventos y Observers — dispatch 1:N, broker-adaptive.
2. Mediator (command bus) — @handles / send, 1:1.
3. Pipeline — pipeline modelo cebolla (estilo Laravel).

Más

1. Correo — Mailables, la facade Mail, drivers (log/SMTP), i18n de correos, Mailpit.
2. Logging — Loguru, JSON, niveles.

---

Mapa mental Laravel → tequio

Laravel	tequio
artisan	jornal
php artisan queue:work	jornal queue work
php artisan schedule:work	jornal schedule work
php artisan schedule:run	jornal schedule run
$schedule->command(...)->everyFiveMinutes()	@cron_task(schedule=...)
dispatch(new X) / Job	@job + .dispatch()
Event / Listener	Event + Observer (auto-descubierto)
Eloquent Model	modelo SQLAlchemy (app/Models)
$table->timestamps()	TimestampMixin
SoftDeletes	soft-delete automático
Repository / Service	Repository[Model, Id] / service @transactional
php artisan migrate	jornal migrate run
php artisan make:model Foo	jornal make model Foo
php artisan db:seed	jornal db seed
config() / .env	settings / .env
Service Provider auto-discovery	auto-discovery por convención (Registry)