report_typst

Generador de reportes PDF usando Typst como motor de renderizado.

Requisitos

• Python 3.11+
• uv

Instalación

uv sync

Instalar en otra libreria

uv add "git+https://github.com/ernestopalacios/report_typst"

Uso rápido

from pathlib import Path
from report_typst import Report, ReportMetadata
from report_typst.renderers.pypi_typst import PyTypstRenderer

report = Report(
    report_type="log_report",
    renderer=PyTypstRenderer(),
    metadata=ReportMetadata(
        id="OT-123",
        estado="EN PROCESO",
        fecha="2025-01-15",
        extra={"cuadrilla": "Alpha", "responsable": "Juan Pérez"},
    ),
    templates_dir=Path("src/report_typst/templates"),
)

report.add_entry("ERROR", "No coinciden las fechas", "Detalle del error...")
report.add_entry("INFO", "Procesamiento completado", "Sin observaciones")

result = report.generate()
print(f"PDF generado: {result.pdf_path}")

Tipos de reporte disponibles

report_type	v1 mapper	Plantilla	Estado
log_report	log_report_v1_mapper	log_report_v1.typ	Estable
marcas_report	marcas_report_v1_mapper	marcas_report_v1.typ	Placeholder

Arquitectura

La clase Report (src/report_typst/core.py) es un traductor puro: recibe datos estructurados y produce un PDF. No contiene lógica de negocio.

• Renderer inyectable: Report recibe un TypstRenderer (Protocol en renderer.py). La implementación de producción es PyTypstRenderer (renderers/pypi_typst.py, basada en el paquete typst de PyPI). Esto permite testear con mocks sin compilar Typst real.
• Tipos de reporte: registrados en report_types.py vía match/case en resolve_report_spec(). Cada tipo define su plantilla .typ y un mapper que transforma LogEntry/ReportMetadata al dict que la plantilla espera.
• Plantillas: .typ en src/report_typst/templates/. Nomenclatura: {report_type}_v{version}.typ.
• Metadatos extensibles: ReportMetadata tiene campos base (id, estado, fecha) y un dict extra para campos específicos de cada proyecto.

Agregar un nuevo tipo de reporte

1. Crear una plantilla mi_reporte_v1.typ en templates/.
2. Escribir un mapper en report_types.py.
3. Agregar un case en resolve_report_spec().

Desarrollo

uv run pytest              # tests unitarios (sin integración)
uv run pytest -m ''        # todos los tests, incluyendo integración
uv run pytest --cov=report_typst   # con cobertura

Los tests de integración compilan Typst real y están marcados con @pytest.mark.integration. Quedan excluidos del run por defecto.

Para más detalles de arquitectura, consultar AGENTS.md.