'unoconv' para facilitar la conversión de documentos

Kevin van Zonneveld

Cofundador · Ámsterdam, Países Bajos · Mostrar bio

Convertir documentos entre distintos formatos es una tarea común para desarrolladores y profesionales. Históricamente, unoconv⁠ fue una herramienta de código abierto que aprovechaba LibreOffice para convertir documentos como DOCX, ODT y XLSX a PDF y otros formatos.

Introducción a 'unoconv' y sus capacidades de código abierto

'Unoconv' (Universal Office Converter) es una utilidad de línea de comandos que aprovecha LibreOffice⁠ para la conversión de documentos. Admite una amplia variedad de formatos de documento, lo que la hace útil para desarrolladores que mantienen sistemas heredados o dan soporte a flujos de trabajo existentes. Aunque unoconv está obsoleto, sirve como ejemplo instructivo de cómo automatizar tareas de conversión de documentos.

Configurar e instalar 'unoconv' en tu sistema

Requisitos previos

Antes de usar 'unoconv', asegúrate de que LibreOffice esté instalado en tu sistema, ya que unoconv depende de él para realizar las conversiones. Ten en cuenta que unoconv puede presentar problemas de compatibilidad con las versiones modernas de Python; considera cambiar a unoserver⁠ para proyectos nuevos.

Instalación en Linux (Ubuntu/Debian)

Para un despliegue heredado existente, comprueba si tu distribución todavía ofrece el paquete unoconv:

apt-cache policy libreoffice unoconv

Instalación en macOS

La fórmula de Homebrew para unoconv está deshabilitada porque su repositorio fue archivado. No uses brew install unoconv para una configuración nueva. Instala LibreOffice y sigue las instrucciones de unoserver para seleccionar un intérprete de Python que pueda importar el módulo uno de LibreOffice:

brew install --cask libreoffice

Instalación en Windows

La compatibilidad nativa de unoconv con Windows es limitada. Recomendamos usar el Subsistema de Windows para Linux (WSL2) y seguir las instrucciones de instalación de Linux para garantizar la compatibilidad.

Casos de uso y escenarios comunes

Los desarrolladores pueden emplear unoconv para diversas tareas, entre ellas:

• Conversiones por lotes: convertir varios archivos DOCX a PDF en una sola operación.
• Automatización de la generación de informes: generar automáticamente informes en PDF a partir de plantillas de documentos.
• Mantenimiento de sistemas heredados: dar soporte y mantener flujos de trabajo que todavía dependen de unoconv.
• Procesamiento del lado del servidor: integrar la conversión de documentos en aplicaciones de back-end para un procesamiento automatizado.

Guía paso a paso: convertir documentos de docx a PDF

La conversión básica con unoconv es sencilla. Para convertir un solo archivo DOCX a PDF, ejecuta:

unoconv -f pdf document.docx

Para un conjunto pequeño dentro de un directorio sin salidas PDF que colisionen:

unoconv -f pdf ./*.docx

Automatizar tareas de conversión de documentos con scripts

Automatizar la conversión de documentos puede agilizar tu flujo de trabajo. El siguiente script de Python muestra cómo convertir archivos DOCX en una instalación de unoconv que ya funciona. Guárdalo como convert_documents.py y ejecuta python3 convert_documents.py docs new-pdfs. Requiere un directorio de salida nuevo, omite directorios y enlaces simbólicos, y publica cada resultado solo después de que el comando se complete correctamente. Si alguna conversión falla, el proceso termina con error después de intentar con los demás archivos.

import os
from pathlib import Path
import subprocess
import sys
from tempfile import TemporaryDirectory


def convert_documents(input_dir, output_dir):
    source = Path(input_dir).resolve(strict=True)
    files = sorted(path for path in source.iterdir()
                   if not path.is_symlink() and path.is_file()
                   and path.suffix.lower() == '.docx')
    if not files:
        print('No DOCX files found', file=sys.stderr)
        return 1
    output = Path(output_dir).absolute()
    output.mkdir(mode=0o700)
    failures = 0
    for path in files:
        try:
            with TemporaryDirectory(prefix='.conversion-', dir=output) as temporary:
                candidate = Path(temporary) / 'result.pdf'
                subprocess.run(
                    ['unoconv', '-f', 'pdf', '-o', str(candidate), str(path)],
                    check=True, timeout=120,
                )
                if not candidate.is_file() or candidate.stat().st_size == 0:
                    raise ValueError('No nonempty PDF was produced')
                # Hard-link publication fails instead of replacing a destination that appeared.
                os.link(candidate, output / (path.stem + '.pdf'))
            print(f'Converted {path.name}')
        except (OSError, ValueError, subprocess.SubprocessError):
            failures += 1
            print(f'Conversion failed: {path.name}', file=sys.stderr)
    return 1 if failures else 0


if __name__ == '__main__':
    if len(sys.argv) != 3:
        sys.exit('Usage: python3 convert_documents.py <input-directory> <new-output-directory>')
    try:
        sys.exit(convert_documents(sys.argv[1], sys.argv[2]))
    except (OSError, ValueError):
        sys.exit('Cannot prepare conversion directories; use an existing input and a new output directory')

El tiempo de espera limita el proceso cliente, no necesariamente el trabajo que ya se está ejecutando en LibreOffice. Usa un proceso de conversión dedicado para archivos no confiables, con límites de recursos del sistema operativo y sin acceso a partes sensibles del sistema de archivos. Comprueba el renderizado, las fuentes y la paginación en documentos representativos; que un comando se ejecute correctamente no garantiza la fidelidad visual.

Solución de problemas comunes

Conflictos de versiones de Python

Los sistemas modernos pueden presentar conflictos de versiones de Python con unoconv. Para resolver estos problemas, puedes:

• Usar un entorno virtual de Python con una versión compatible.
• Instalar una versión específica de Python que funcione bien con unoconv.
• Cambiar a unoserver, que ofrece mejor compatibilidad con Python 3.

Compatibilidad de versiones de LibreOffice

Asegúrate de que tu instalación de LibreOffice sea compatible con unoconv:

libreoffice --version
unoconv --version

Consideraciones para el despliegue en contenedores

Para entornos en contenedores, ten en cuenta lo siguiente:

• Compilar a partir de una distribución compatible e instalar sus paquetes de LibreOffice.
• Asegurarte de que las fuentes necesarias estén instaladas.
• Configurar los permisos de archivo apropiados.

Estos pasos ayudan a evitar errores durante la conversión de documentos en despliegues en contenedores.

Alternativas modernas y comparación

Unoserver (recomendado)

Unoserver es el sucesor de unoconv. Proporciona un proceso de LibreOffice de larga duración y un cliente unoconvert independiente. Su intérprete de Python debe poder importar uno; un entorno virtual cualquiera no es suficiente. Para una integración completa, consulta conversión de documentos desde Rust.

LibreOffice CLI

El propio LibreOffice ofrece una opción de conversión nativa desde la línea de comandos que evita la necesidad de unoconv. Para convertir un archivo DOCX a PDF con la CLI de LibreOffice, ejecuta:

soffice --headless --convert-to pdf document.docx

Soluciones en la nube

Para entornos de producción escalables, considera servicios de conversión de documentos en la nube o soluciones en contenedores que ofrezcan mayor fiabilidad y un mantenimiento sin esfuerzo.

Conclusión

Aunque unoconv ha servido bien a los desarrolladores a lo largo de los años, su obsolescencia implica que los proyectos nuevos deberían considerar alternativas modernas como unoserver o servicios de conversión en la nube. Si mantienes sistemas heredados, presta atención a la compatibilidad y a posibles problemas con las versiones de Python.

Si buscas una solución robusta y escalable para la conversión de documentos, considera explorar el servicio de conversión de documentos de Transloadit.