Herramientas. Python-docx

Biblioteca python-docx (2) Tablas y gráficos

Aclarar antes de nada que estoy empleando el término gráfico como sinónimo de imagen, con independencia de que esta imagen represente un paisaje, una persona o un gráfico de barrar. Dicho esto, en esta entrada trataré sobre estos potenciales componentes de un documento de texto por ser elementos que se pueden necesitar para la elaboración de los documentos que solemos crear como SEO. La finalidad de tratar estos temas es, como en otras ocasiones, proveer de recursos para la intervención profesional de los SEO; muy lejos de la de hacer a un OE experto en el manejo de Python-docx.

Desde esta orientación eminentemente práctica, empecemos por aprender a incluir gráficos (imágenes) en nuestro documento. Para ello, y dando por resueltos los procesos previos de creación del documento y la inclusión de los contenidos ya conocidos por la entrada anterior,  para incluir una imagen en un texto es suficiente con hacer uso de la función add_picture(), que precisa obligatoriamente un único parámetro; un string con la dirección de la imagen, incluyendo nombre y extensión, si bien cuando la imagen está en el mismo directorio que el script, es suficiente con el nombre y extensión.

Es posible pasar otros dos parámetros o sólo uno de ellos, con la indicación dimensional (height y/o width) y el o los valores necesarios para dimensionar la imagen en pulgadas (v.g. width=Inches(1.25)). Así es en nuestro este caso (documento.add_picture('Aprendizaje.jpg', width=Inches(1.25))) y por ese motivo necesitamos indicar al inicio del script que también precisamos importar el manejo de Inches (from docx.shared import Inches)

Sigamos ahora con las tareas necesarias para implementar una tabla en el documento, empezando por los datos que ésta va a contener, los cuales son tratados en nuestro documento de ejemplo como registros de una base de datos, motivo por el que creamos una tupla de tuplas que contiene tantos registros como deseemos y cada uno de ellos tantos elementos como columnas va a tener nuestra tabla.

registros = (('3', 'Entrevistas', 101),('4', 'Reuniones', 42),('5','Evaluaciones', 36))

No es precisamente la forma más sencilla de trabajar (y crear) una tabla, pero así aprendemos cómo podemos manejar el acceso a sus celdas para introducir los datos que deseamos contengan.

Pero crear la tabla es en realidad mucho más sencillo, siendo suficiente con emplear la función add_table(), que requiere dos parámetros integer: las columnas y las filas (tabla = documento.add_table(rows=1, cols=3))

Las complicaciones empiezan cuando decidimos que nuestra tabla tiene que tener un encabezado que clarifique su lectura. En ese caso (que es opcional, recuerdo) se requiere crear una variable (encabezado) que referencie la siguiente expresión (encabezado = tabla.rows[0].cells). Gracias a ella podemos acceder a las celdas (.cells) primera fila (rows[0].cells) de la tabla creada (tabla.rows[0].cells). Sobre esta variable iremos identificando cada una de las celdas del encabezado e incluyendo en ellas el texto del mismo (vg encabezado[0].text = 'Identificador')

Para incluir ahora el contenido de nuestros registros en la tabla, en este caso (y es un buen ejemplo de cómo podemos actuar) utilizamos un bucle for de cierta complejidad en cuanto a formulación, pero sumamente funcional (for id, cont, num in registros:). Básicamente lo que hace este bucle es recorrer nuestra base de datos (registros), elemento por elemento (id, cont, num in registros:) para posicionarlos según los criterios establecidos (vg, primero (primera celda de la fila) ... row_cells[0].text = id, después...) según la estructura a la que anteriormente se ha accedido, asociándola a la variable row_cells gracias a la función add_row() (row_cells = tabla.add_row().cells). 

Obsérvese que esta instrucción (row_cells = tabla.add_row().cells) es muy similar, pero en realidad muy diferente de la que nos sirvió para crear el encabezado (encabezado = tabla.rows[0].cells), por lo que no deben confundirse.

Este uso del bucle for puede que nos resulte un poco complicado en estos momentos (aun estamos empezando a programar en Python), así que necesitamos conocer otra forma de utilizar una tabla, como, por ejemplo, para una función muy común en la composición de un texto: posicionar texto (una serie de párrafos) de forma tabular. Para estos casos podemos trabajar con un código más sencillo. Veamos:

• Creamos la tabla igual que antes (tabla2 = documento.add_table(rows = 2, cols = 2))
• Accedemos a la primera fila (celdas0 = tabla2.rows[0].cells), como ves con el mismo procedimiento que antes usamos para crear el encabezado
• Y posicionamos el contenido textual en las celdas de esa fila (v.g. celdas0[0].text = "Primera")

Deberemos repetir el procedimiento para cada una de las filas (celdas1 = tabla2.rows[1].cells) y sus respectivas celdas (celdas1[0].text = "Segunda"), ya que por algo es un procedimiento manual. Pero estoy seguro que dentro de poco sabremos implementar un bucle para agilizar el procedimiento, no tan elegante y complejo como el presentado antes, pero suficiente para nuestros fines.

Documento. Desde este enlace puedes ver (y descargar) el script que contiene el código de esta entrada.