catslap 1.0.0

Catslap loads JSON input and applies it to document templates to generate final outputs

catslap

Author: Luis Alberto González MIT License Copyright 2026

catslap es una librería Python para la generación automática de documentos a partir de datos estructurados en JSON y plantillas parametrizables. Permite producir documentos finales en múltiples formatos evaluando directrices incrustadas directamente en las plantillas.

Características principales

• Generación de documentos a partir de un archivo JSON de entrada.
• Soporte para múltiples formatos de salida:
  • Word
  • PowerPoint
  • Excel
  • HTML
  • JavaScript
  • Texto plano
• Admite plantillas simples o múltiples:
  • Un único archivo.
  • Varios archivos empaquetados en un ZIP o contenidos en un directorio.
• Posibilidad de limitar las extensiones de archivos de plantilla a procesar.
• Evaluación de expresiones y lógica con semántica Python.
• Renderización de HTML embebido en los datos JSON para formatos enriquecidos (Word y PowerPoint).

Concepto general

El flujo de trabajo de catslap es el siguiente:

1. Se proporciona un archivo JSON con los datos de entrada.
2. Se define uno o varios documentos que contienen directrices y que serán las plantillas de salida.
3. catslap evalúa las directrices de los documentos plantilla, accede a los datos JSON y resuelve los datos dinámicos obteniendo los documentos finales en el mismo formato y estilo que en la plantilla original.

Uso en línea de comandos

catslap puede ejecutarse como script para generar documentos desde un JSON de entrada y una plantilla (archivo, directorio o ZIP).

Ejemplos:

python src/catslap/catslap.py datos.json plantilla.docx salida.docx
python src/catslap/catslap.py datos.json plantillas/ salida/
python src/catslap/catslap.py datos.json plantillas.zip salida/ -v
python src/catslap/catslap.py datos.json plantillas/ salida/ -x .docx .xlsx

Parámetros:

• json_file: ruta al archivo JSON de entrada.
• template: archivo de plantilla, directorio de plantillas o ZIP.
• output: archivo de salida o directorio de salida.
• -v / --verbose: muestra información de alto nivel del proceso.
• -x / --ext: filtra por extensiones permitidas (por ejemplo .docx .xlsx).

Acceso a datos desde la plantilla

El acceso a los datos del JSON se realiza mediante expresiones delimitadas por {{ ... }}. La evaluación sigue el comportamiento de Python como si el JSON fuera un dict, con el añadido de permitir acceso mediante el operador de punto.

Ejemplo de JSON de entrada

{
  "report_name": "My report",
  "report_data": {
    "name": "BBS Tennesy",
    "account": "0000123",
    "values": [43, 56, 991, 2]
  }
}

Ejemplos de acceso a datos

{{report_data.account}}
{{report_data.get('account')}}
{{report_data['account']}}

Hay que tener especial cuidado con usar nombres de JSON que correspondan a tokens de Python para evitar problemas de evaluación. Por ejemplo, si se usa items dentro de un JSON, no se podría acceder a ese elemento mediante el operador punto (por ejemplo, data.items), pero sí se podría acceder mediante data['items'] o data.get('items')

Cuando un valor del JSON contiene código HTML (comienza por una etiqueta HTML), este será renderizado de forma enriquecida en el formato de salida, siempre que el tipo de formato de documento lo permita.

Directrices de plantilla

Las directrices se definen usando bloques {% ... %} y cada directriz debe ocupar un párrafo completo dentro de la plantilla.

Tipos de directrices soportadas

• Bucles
• Condiciones
• Configuraciones (dependientes del formato de salida)

Bucles

Permiten iterar sobre listas del JSON. La sintaxis es:

{% for <name> in <list-expression> %}
...
{% endfor %}

Ejemplo:

{% for value in report_data.values %}
  {{value}}
{% endfor %}

Condiciones

Permiten la ejecución condicional de bloques de contenido. La condición se evalúa como una expresión Python.

{% if report_data.account %}
  Cuenta válida
{% else %}
  Cuenta no definida
{% endif %}

Configuraciones de estilo (Word y PowerPoint)

Para documentos Word y PowerPoint, catslap permite definir cómo se renderiza el HTML encontrado en los datos JSON mediante directrices de estilo. El formato de la directriz de estilo es:

{% style <keyword>=<style_name> %}

<keyword> son estilos predefinidos en catslap correspondientes a estilos de HTML. <style_name> es el nombre del estilo que se utilizará de entre los estilos definidos en el documento de plantilla de Word o PowerPoint.

Ejemplo de configuración de estilos

{% style heading=Título 1 %}
{% style table_cell=Celda normal %}
{% style table_header=Celda cabecera %}
{% style table_header_bgcolor=#FF0000 %}
{% style table_cell_bgcolor=white %}
{% style table_cell_bgcolor2=#E8E8E8 %}
{% style table_caption=Tabla título %}
{% style code=Code %}
{% style codeblock=Codeblock %}
{% style token=Token %}
{% style link_title=LinkTitle %}
{% style link_url=LinkUrl %}
{% style quote=Cita destacada %}

Estilos soportados

• heading Define el estilo para títulos HTML (<H1> a <H6>). Si se define un único estilo, se generan automáticamente los estilos sucesivos prefijados con el número 2, 3, 4, 5 y 6. Por defecto, ya está definido con los estilos: "Título1", ..., "Título6"

• paragraph Define el estilo para párrafos HTML <P>. Por defecto se usa el estilo "Normal"

• list_bullet Define el estilo para listas HTML <UL>. Si se define un único estilo, se generan automáticamente los estilos sucesivos prefijados con el número 2, 3, 4, 5 y 6 para las sucesivas identaciones de lista. Por defecto, ya está definido con los estilos: "Lista con viñetas1", ..., "Lista con viñetas6"

• list_number Define el estilo para listas HTML <OL>. Si se define un único estilo, se generan automáticamente los estilos sucesivos prefijados con el número 2, 3, 4, 5 y 6 para las sucesivas identaciones de lista. Por defecto, ya está definido con los estilos: "Lista con números1", ..., "Lista con números6"

• table_cell Estilo de los párrafos dentro de <TD>.

• table_header Estilo de los párrafos dentro de <TH>.

• table_header_bgcolor Color de fondo por defecto de las cabeceras de tabla.

• table_cell_bgcolor Color de fondo por defecto de las celdas de tabla.

• table_cell_bgcolor2 Color de fondo alternativo para filas impares (opcional).

• table_caption Estilo del párrafo para <CAPTION>.

• code Estilo de carácter para contenido dentro de <code>.

• codeblock Estilo de párrafo para bloques <pre>.

• token Estilo de párrafo para <div class="token">.

• link_title Estilo de párrafo para el texto de los enlaces.

• link_url Estilo de párrafo para la URL de los enlaces.

• quote Estilo de párrafo para bloques de cita destacados.

Estilos personalizados

• xxxxx Define el estilo para cualquier etiqueta HTML que incluya entre su atributo class el nombre style_xxxxx, siempre que xxxxx no corresponda a cualquiera de los nombres de estilo predefinidos anteriores. Por ejemplo: En el documento Word de plantilla se define: {% style mystyle=Cabecera personalizada %} En los datos JSON se define un contenido como: <div class="style_mystyle">Lorem ipsum...</div> La renderización del documento final generará un párrafo de Word con el estilo "Cadecera Personalizada"

Renderización de HTML (Word y PowerPoint)

catslap soporta la interpretación de un subconjunto de HTML para generar documentos enriquecidos.

Etiquetas soportadas

• <P>: Párrafos, con soporte de CSS:

  • text-align
  • color
  • font-weight
  • font-style
  • text-decoration

• <H1> a <H6>: Títulos de capítulo.

• <OL>, <UL>, <LI>: Listas ordenadas y desordenadas.

• <PRE>: Bloques de código.

• <BLOCKQUOTE>: Citas destacadas.

• <CODE>: Código en línea.

• <EM>, <I>: Itálica.

• <STRONG>, <B>: Negrita.

• <U>: Subrayado.

• <STROKE>: Texto tachado.

• <FONT color="">: Color de texto (también mediante CSS color).

• <TABLE>, <TR>, <TD>, <TH>, <CAPTION>, <THEAD>, <TBODY>: Definición de tablas.

• <IMG>: Imágenes.

• <A href="">...</A>. Enlaces.

• <DIV class="<style>">: Aplicación de estilos de bloque predefinidos (token, table_cell, codeblock, etc.).

• <SPAN class="<style>">: Aplicación de estilos a nivel de caracteres predefinidos (solo code).

• <DIV class="style_<style>">: Aplicación de estilos de bloque personalizados.

• <SPAN class="style_<style>">: Aplicación de estilos a nivel de caracteres personalizados.

Licencia

MIT License Copyright 2026 Luis Alberto González Rivas