---
id: "0020"
title: "PDF Generation"
status: completado
type: feature
domain: []
scope: multi-app
priority: media
depends: []
blocks: []
related: []
created: 2026-05-17
updated: 2026-05-17
tags: []
---
# 0020 — PDF Generation

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | 0020 |
| **Estado** | pendiente |
| **Prioridad** | media |
| **Tipo** | feature |

## Dependencias

Ninguna.

---

## Objetivo

Crear funciones para generar y construir PDFs programaticamente: reportes, facturas, exports de datos, conversiones desde HTML/Markdown. Complementa las funciones de lectura de PDF ya existentes (`pdf_to_markdown_py_core`, `extract_pdf_text_py_core`, `extract_pdf_bookmarks_py_core`) con la capacidad inversa de crear documentos.

## Contexto

- El registry tiene 3 funciones para **leer** PDFs y 2 pipelines relacionados (`export_analysis_pdfs_bash_pipelines`, `notebook_to_pdf_bash_infra`), pero **cero** funciones para **generar** PDFs desde datos o contenido.
- Casos de uso frecuentes que hoy requieren codigo ad-hoc: generar reportes de ejecuciones, exportar tablas de datos como PDF, crear facturas, convertir documentacion markdown a PDF distribuible.
- Python tiene las mejores librerias de generacion de PDF (reportlab, fpdf2, weasyprint) sin necesidad de binarios externos como wkhtmltopdf.
- Go puede cubrir casos simples de reportes sin dependencias pesadas, usando `go-pdf/fpdf`.
- El dominio natural es `infra` porque generar archivos es I/O, igual que las funciones de export/deploy existentes.

## Arquitectura

### Python (dominio infra) — generacion completa

```
python/functions/infra/
├── pdf_create.py               — NEW: crear documento PDF nuevo
├── pdf_create.md               — NEW
├── pdf_add_page.py             — NEW: añadir pagina con tamaño/orientacion
├── pdf_add_page.md             — NEW
├── pdf_add_text.py             — NEW: añadir bloque de texto con estilo
├── pdf_add_text.md             — NEW
├── pdf_add_table.py            — NEW: añadir tabla con datos, headers, anchos
├── pdf_add_table.md            — NEW
├── pdf_add_image.py            — NEW: añadir imagen desde archivo o bytes
├── pdf_add_image.md            — NEW
├── pdf_add_header_footer.py    — NEW: header/footer recurrente con numeros de pagina
├── pdf_add_header_footer.md    — NEW
├── pdf_from_html.py            — NEW: HTML string → PDF
├── pdf_from_html.md            — NEW
├── pdf_from_markdown.py        — NEW: Markdown → HTML → PDF
├── pdf_from_markdown.md        — NEW
├── pdf_merge.py                — NEW: fusionar multiples PDFs en uno
├── pdf_merge.md                — NEW
├── pdf_save.py                 — NEW: guardar PDF a archivo o retornar bytes
├── pdf_save.md                 — NEW

python/types/infra/
├── pdf_doc.py                  — NEW: tipo PDFDoc
├── pdf_doc.md                  — NEW
├── pdf_page.py                 — NEW: tipo PDFPage
├── pdf_page.md                 — NEW
├── pdf_style.py                — NEW: tipo PDFStyle
├── pdf_style.md                — NEW
```

### Go (dominio infra) — reportes simples

```
functions/infra/
├── pdf_simple_report.go        — NEW: generar PDF simple desde titulo + secciones + tablas
├── pdf_simple_report.md        — NEW
```

### Patron pure core / impure shell

Todas las funciones de generacion son impuras (escriben estado en un objeto documento mutable y/o hacen I/O a disco). No hay funciones puras en esta issue porque la generacion de PDFs es inherentemente stateful.

Los tipos (`PDFDoc`, `PDFPage`, `PDFStyle`) son product types que definen la estructura de datos, no tienen I/O.

## Diseño

### Tipos

```python
@dataclass
class PDFStyle:
    font_family: str = "Helvetica"
    font_size: float = 12.0
    color: str = "#000000"          # hex color
    alignment: str = "left"         # left, center, right, justify
    line_height: float = 1.2
    margin_top: float = 0.0
    margin_bottom: float = 2.0

@dataclass
class PDFPage:
    width: float = 210.0            # mm (A4 default)
    height: float = 297.0           # mm (A4 default)
    orientation: str = "portrait"   # portrait, landscape

@dataclass
class PDFDoc:
    pages: list                     # lista de paginas con contenido
    title: str = ""
    author: str = ""
    subject: str = ""
    default_font: str = "Helvetica"
    margin_left: float = 20.0       # mm
    margin_right: float = 20.0
    margin_top: float = 20.0
    margin_bottom: float = 20.0
```

### Funciones Python

| Funcion | ID | Purity | Firma (simplificada) |
|---------|-----|--------|---------------------|
| `pdf_create` | `pdf_create_py_infra` | impure | `(title, author, page_size, margins) -> PDFDoc` |
| `pdf_add_page` | `pdf_add_page_py_infra` | impure | `(doc, orientation, width, height) -> PDFDoc` |
| `pdf_add_text` | `pdf_add_text_py_infra` | impure | `(doc, text, style, x, y) -> PDFDoc` |
| `pdf_add_table` | `pdf_add_table_py_infra` | impure | `(doc, headers, rows, col_widths, style) -> PDFDoc` |
| `pdf_add_image` | `pdf_add_image_py_infra` | impure | `(doc, image_path_or_bytes, x, y, width, height) -> PDFDoc` |
| `pdf_add_header_footer` | `pdf_add_header_footer_py_infra` | impure | `(doc, header_text, footer_text, page_numbers) -> PDFDoc` |
| `pdf_from_html` | `pdf_from_html_py_infra` | impure | `(html_string, output_path, page_size) -> str` |
| `pdf_from_markdown` | `pdf_from_markdown_py_infra` | impure | `(markdown_string, output_path, css) -> str` |
| `pdf_merge` | `pdf_merge_py_infra` | impure | `(pdf_paths, output_path) -> str` |
| `pdf_save` | `pdf_save_py_infra` | impure | `(doc, output_path) -> str \| bytes` |

### Funcion Go

| Funcion | ID | Purity | Firma (simplificada) |
|---------|-----|--------|---------------------|
| `pdf_simple_report` | `pdf_simple_report_go_infra` | impure | `(title string, sections []Section, outputPath string) (string, error)` |

La funcion Go recibe un titulo, una lista de secciones (cada una con titulo, texto y tabla opcional) y genera un PDF completo en un solo paso. No expone el builder granular de Python — es una funcion de alto nivel para reportes rapidos sin dependencia de Python.

## Tareas

### Fase 1: Tipos y builder basico

- [ ] **1.1** Crear tipos `PDFDoc`, `PDFPage`, `PDFStyle` en `python/types/infra/` con `.py` y `.md`
- [ ] **1.2** `pdf_create` — inicializa documento fpdf2, retorna wrapper PDFDoc
- [ ] **1.3** `pdf_add_page` — añade pagina con orientacion y tamaño configurables
- [ ] **1.4** `pdf_add_text` — escribe texto con fuente, tamaño, color, posicion
- [ ] **1.5** `pdf_save` — serializa documento a archivo o retorna bytes
- [ ] **1.6** Tests basicos: crear documento, añadir pagina, escribir texto, guardar, verificar que el PDF resultante es valido

### Fase 2: Contenido rico

- [ ] **2.1** `pdf_add_table` — tabla con headers, filas, anchos de columna, bordes, colores alternados
- [ ] **2.2** `pdf_add_image` — imagen desde path o bytes, redimensionado automatico si se especifica solo ancho o alto
- [ ] **2.3** `pdf_add_header_footer` — header/footer recurrente, numero de pagina con formato configurable (`Pagina {n} de {total}`)
- [ ] **2.4** `pdf_merge` — fusionar N archivos PDF en uno usando PyPDF2 (ya es dependencia del registry)
- [ ] **2.5** Tests: tabla con datos reales, imagen embebida, merge de 3 PDFs

### Fase 3: Conversiones

- [ ] **3.1** `pdf_from_html` — HTML a PDF usando weasyprint. Soporta CSS inline y externo.
- [ ] **3.2** `pdf_from_markdown` — Markdown a HTML (via `markdown` o `mistune`) y luego a PDF con weasyprint. CSS por defecto incluido.
- [ ] **3.3** Tests: HTML con tabla y estilos a PDF, markdown con headers y listas a PDF
- [ ] **3.4** Documentar instalacion de dependencias de weasyprint (librerias de sistema: pango, cairo, gdk-pixbuf)

### Fase 4: Go y cleanup

- [ ] **4.1** `pdf_simple_report` en Go con `go-pdf/fpdf` — titulo, secciones con texto, tablas opcionales
- [ ] **4.2** Tests Go con verificacion de output valido
- [ ] **4.3** `fn index` y verificar que todas las funciones y tipos aparecen en registry.db
- [ ] **4.4** Verificar `go vet -tags fts5` y tests Python

---

## Ejemplo de uso

### Factura

```python
from infra import pdf_create, pdf_add_page, pdf_add_text, pdf_add_table
from infra import pdf_add_image, pdf_save
from infra import PDFStyle

doc = pdf_create(title="Factura #2024-0042", author="Mi Empresa S.L.")
doc = pdf_add_page(doc)

# Logo
doc = pdf_add_image(doc, "assets/logo.png", x=15, y=10, width=40)

# Datos empresa
header = PDFStyle(font_size=10, color="#666666")
doc = pdf_add_text(doc, "Mi Empresa S.L.\nCIF: B12345678\nCalle Principal 42", style=header, x=120, y=10)

# Titulo
titulo = PDFStyle(font_size=22, font_family="Helvetica-Bold", color="#333333")
doc = pdf_add_text(doc, "FACTURA #2024-0042", style=titulo, x=15, y=55)

# Tabla de items
headers = ["Concepto", "Cantidad", "Precio", "Total"]
rows = [
    ["Consultoria tecnica", "40 h", "75.00 EUR", "3,000.00 EUR"],
    ["Desarrollo API", "1", "2,500.00 EUR", "2,500.00 EUR"],
    ["Hosting mensual", "3 meses", "50.00 EUR", "150.00 EUR"],
]
doc = pdf_add_table(doc, headers, rows, col_widths=[80, 30, 40, 40])

# Total
total = PDFStyle(font_size=16, font_family="Helvetica-Bold", alignment="right")
doc = pdf_add_text(doc, "TOTAL: 5,650.00 EUR", style=total)

pdf_save(doc, "factura_2024_0042.pdf")
```

### Reporte de datos

```python
from infra import pdf_create, pdf_add_page, pdf_add_text, pdf_add_table
from infra import pdf_add_header_footer, pdf_save
from infra import PDFStyle

# Generar reporte desde resultados de query
doc = pdf_create(title="Reporte Mensual - Abril 2026")
doc = pdf_add_header_footer(doc,
    header_text="Reporte Mensual",
    footer_text="Pagina {n} de {total}",
    page_numbers=True
)
doc = pdf_add_page(doc)

titulo = PDFStyle(font_size=18, font_family="Helvetica-Bold")
doc = pdf_add_text(doc, "Resumen de Ejecuciones — Abril 2026", style=titulo)

doc = pdf_add_text(doc, f"Total ejecuciones: {len(executions)}")
doc = pdf_add_text(doc, f"Tasa de exito: {success_rate:.1f}%")
doc = pdf_add_text(doc, f"Duracion promedio: {avg_duration:.0f} ms")

headers = ["Pipeline", "Ejecuciones", "Exitos", "Fallos", "Duracion avg"]
doc = pdf_add_table(doc, headers, execution_summary_rows)

pdf_save(doc, "reporte_abril_2026.pdf")
```

### Export de Markdown a PDF

```python
from infra import pdf_from_markdown

# Convertir documentacion a PDF distribuible
with open("docs/spec_operaciones.md") as f:
    md_content = f.read()

output = pdf_from_markdown(md_content, "spec_operaciones.pdf",
    css="body { font-family: sans-serif; } code { background: #f5f5f5; }"
)
print(f"PDF generado: {output}")
```

### Reporte simple en Go

```go
sections := []infra.ReportSection{
    {
        Title: "Estado del Registry",
        Text:  "El registry contiene 142 funciones, 38 tipos y 12 proposals pendientes.",
    },
    {
        Title: "Funciones por Dominio",
        Table: &infra.ReportTable{
            Headers: []string{"Dominio", "Funciones", "Tipos"},
            Rows: [][]string{
                {"core", "45", "12"},
                {"infra", "38", "8"},
                {"finance", "22", "6"},
                {"datascience", "18", "5"},
            },
        },
    },
}

path, err := infra.PdfSimpleReport("Registry Status Report", sections, "registry_report.pdf")
if err != nil {
    log.Fatal(err)
}
fmt.Println("Reporte generado:", path)
```

## Decisiones de diseño

- **fpdf2 para Python (builder granular):** Libreria ligera, pure Python, sin dependencias binarias. Cubre el 90% de los casos (texto, tablas, imagenes). No requiere instalacion de sistema.
- **weasyprint para HTML/Markdown → PDF:** Cuando se necesita layout CSS completo (columnas, grids, estilos complejos). Requiere librerias de sistema (pango, cairo) pero produce PDFs de alta calidad tipografica.
- **PyPDF2 para merge:** Ya es dependencia del registry (usada por `extract_pdf_text_py_core`). No añade dependencias nuevas.
- **go-pdf/fpdf para Go:** Zero-dependency, API simple, suficiente para reportes tabulares sin necesidad de layout CSS.
- **Dominio infra (no core):** Generar archivos es I/O, todas las funciones son impuras. Consistente con `notebook_to_pdf_bash_infra` y las funciones de export existentes.
- **API fluent (doc = fn(doc, ...)):** Cada funcion recibe el documento y lo retorna modificado. Permite encadenar operaciones y mantiene la composabilidad funcional del registry. Internamente muta el objeto fpdf2 — la interfaz inmutable es una convencion, no una garantia.
- **`pdf_simple_report` en Go como funcion de alto nivel:** No replica el builder granular de Python. Es una funcion unica que genera un reporte completo desde datos estructurados. Para PDFs complejos, usar Python.
- **Separar builder (pdf_create/add_*/save) de conversiones (pdf_from_html/markdown/merge):** Dos patrones de uso distintos que no comparten estado. El builder construye desde cero; las conversiones transforman contenido existente.

## Riesgos

- **Dependencias de sistema para weasyprint:** pango, cairo, gdk-pixbuf deben estar instalados. En la maquina de desarrollo esto es un `apt install` pero complica portabilidad. Mitigado documentando la instalacion en la fase 3 y haciendo que `pdf_from_html`/`pdf_from_markdown` fallen con mensaje claro si weasyprint no esta disponible. Las funciones del builder (fpdf2) no tienen este problema.
- **Tamaño de PDFs generados:** Imagenes grandes embebidas sin compresion pueden generar PDFs pesados. Mitigado con compresion JPEG automatica en `pdf_add_image` y documentando limites recomendados.
- **Diferencias tipograficas entre SO:** Las fuentes disponibles varian entre Linux/Mac/Windows. Mitigado usando Helvetica (built-in en fpdf2) como fuente por defecto, que no requiere archivos .ttf externos.
- **go-pdf/fpdf es una dependencia Go nueva:** Añade un import al modulo. Mitigado porque es una libreria estable, sin dependencias transitivas, y solo la usa una funcion.

## Criterios de aceptacion

- [ ] `pdf_create` + `pdf_add_page` + `pdf_add_text` + `pdf_save` genera un PDF valido que se puede abrir
- [ ] `pdf_add_table` renderiza tabla con headers, bordes y datos alineados
- [ ] `pdf_add_image` embebe PNG y JPEG correctamente
- [ ] `pdf_from_markdown` convierte markdown con headers, listas y codigo a PDF legible
- [ ] `pdf_merge` combina 3+ PDFs sin corrupcion
- [ ] `pdf_simple_report` en Go genera PDF con titulo, texto y tabla
- [ ] Todos los IDs siguen formato `{name}_py_infra` / `{name}_go_infra`
- [ ] `fn index` registra las 10 funciones Python, 1 funcion Go y 3 tipos sin errores
- [ ] Tests pasan en Python y Go
