Habilidad PDF
Cuándo usarla
- Leer o revisar contenido PDF donde el diseño y los elementos visuales importen.
- Crear PDFs de forma programática con formato confiable.
- Validar la representación final antes de la entrega.
Flujo de trabajo
- Prefiere revisión visual: renderiza páginas PDF a PNG e inspecciónalas.
- Usa
pdftoppmsi está disponible. - Si no está disponible, instala Poppler o pídele al usuario que revise el resultado localmente.
- Usa
- Usa
reportlabpara generar PDFs al crear nuevos documentos. - Usa
pdfplumber(opypdf) para extraer texto y realizar verificaciones rápidas; no confíes en él para la fidelidad del diseño. - Después de cada actualización significativa, vuelve a renderizar las páginas y verifica la alineación, el espaciado y la legibilidad.
Convenciones de archivos temporales y salida
- Usa
tmp/pdfs/para archivos intermedios; elimínalos al terminar. - Escribe los artefactos finales en
output/pdf/cuando trabajes en este repositorio. - Mantén los nombres de archivo estables y descriptivos.
Dependencias (instalar si faltan)
Prefiere uv para la gestión de dependencias.
Paquetes de Python:
uv pip install reportlab pdfplumber pypdf
Si uv no está disponible:
python3 -m pip install reportlab pdfplumber pypdf
Herramientas del sistema (para renderizado):
# macOS (Homebrew)
brew install poppler
# Ubuntu/Debian
sudo apt-get install -y poppler-utils
Si la instalación no es posible en este entorno, indica al usuario qué dependencia falta y cómo instalarla localmente.
Entorno
No se requieren variables de entorno.
Comando de renderizado
pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX
Expectativas de calidad
- Mantén un diseño visual pulido: tipografía consistente, espaciado, márgenes y jerarquía de secciones.
- Evita problemas de renderizado: texto cortado, elementos superpuestos, tablas rotas, cuadrados negros o glifos ilegibles.
- Los gráficos, tablas e imágenes deben ser nítidos, alineados y claramente etiquetados.
- Usa solo guiones ASCII. Evita U+2011 (guión de no separación) y otros guiones Unicode.
- Las citas y referencias deben ser legibles para humanos; nunca dejes tokens de herramientas o cadenas de marcador de posición.
Verificaciones finales
- No entregues hasta que la última inspección PNG muestre cero defectos visuales o de formato.
- Confirma que los encabezados/pies de página, la numeración de páginas y las transiciones entre secciones se vean pulidos.
- Mantén los archivos intermedios organizados o elimínalos después de la aprobación final.