Habilidad Docx
Crear, leer, editar y usar plantillas de archivos .docx de Microsoft Word con
python-docx a través de pequeñas CLI. Maneja texto, estilos, listas, tablas,
imágenes, encabezados/pies de página, plantillas {{token}}, cambios controlados
(listar/aceptar/rechazar), comentarios (listar/añadir/eliminar), campos de TDC e
índice de páginas, y comprobaciones de integridad del paquete. No renderiza
documentos por sí mismo (PDF necesita LibreOffice — ver Conversión a PDF) ni
edita .doc heredados.
Cuándo Usarlo
- El usuario pide generar un documento de Word (informe, carta, contrato).
- Necesitas el texto, esquema, estilos o imágenes incrustadas de un
.docx. - Debes modificar un
.docxexistente: reemplazar texto, editar celdas de tabla, insertar/eliminar párrafos, aplicar estilos, fusionar fragmentos de ejecución. - Tienes una plantilla
.docxcon{{placeholders}}para completar con datos. - El documento tiene cambios controlados para revisar, aceptar o rechazar.
- Necesitas leer los comentarios de los revisores, o añadir/eliminar comentarios.
- Un
.docxno se abre o se comporta de forma extraña y necesitas un diagnóstico. - El documento necesita una tabla de contenido o pies de página "Página X de Y".
- No para:
.doc(heredado),.odto trabajo de maquetación WYSIWYG.
Prerrequisitos
- Python 3.10+ con
python-docxinstalado:pip install python-docx(el nombre de importación esdocx; lxml viene con él). comments addusa la API nativa en python-docx >= 1.2 y un fallback XML en versiones anteriores — ambos son automáticos.- Para bloques de imagen: los archivos de imagen deben existir localmente (PNG/JPEG).
Cómo Ejecutar
Todos los ayudantes viven en scripts/ junto a este archivo. Ejecútalos con la
herramienta terminal; cada uno soporta --help e imprime JSON en stdout.
python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx
Referencia Rápida
| Tarea | Comando |
|---|---|
| Crear desde especificación JSON | docx_create.py spec.json out.docx |
| Texto completo (cuerpo+tablas+encabezados/pies) | docx_read.py f.docx --text |
| Esquema de títulos + formas de tablas | docx_read.py f.docx --structure |
| Estilos realmente usados | docx_read.py f.docx --styles |
| Extraer imágenes incrustadas | docx_read.py f.docx --images outdir/ |
| Detectar cambios controlados/comentarios | docx_read.py f.docx --revisions |
| Buscar/reemplazar (formato conservado) | docx_edit.py replace f.docx --find A --replace B -o out.docx |
| Establecer una celda de tabla | docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X |
| Insertar párrafo antes del índice N | docx_edit.py insert f.docx --index N --text X --style Normal |
| Eliminar párrafo N | docx_edit.py delete f.docx --index N |
| Aplicar estilo al párrafo N | docx_edit.py style f.docx --index N --style "Heading 1" |
| Fusionar ejecuciones adyacentes de igual formato | docx_edit.py normalize f.docx -o out.docx |
| Insertar campo TDC antes del párrafo N | docx_edit.py toc f.docx --index N -o out.docx |
| Campos de pie "Página X de Y" | docx_edit.py page-numbers f.docx |
Rellenar {{tokens}} | docx_template.py tpl.docx values.json out.docx --strict |
| Listar revisiones (id/autor/fecha/texto) | docx_revisions.py list f.docx |
| Aceptar / rechazar todas las revisiones | docx_revisions.py accept-all f.docx -o out.docx (o reject-all) |
| Aceptar / rechazar una revisión | docx_revisions.py accept f.docx --id 3 -o out.docx |
| Listar comentarios (+texto anclado) | docx_comments.py list f.docx |
| Añadir comentario anclado a texto | docx_comments.py add f.docx --target "frase" --text "nota" --author Tú |
| Eliminar comentario por id | docx_comments.py delete f.docx --id 0 |
| Comprobar integridad del paquete | docx_validate.py f.docx (código de salida 1 en errores) |
Procedimiento
- Crear. Escribe una especificación JSON con
write_file, luego ejecutascripts/docx_create.py. La especificación soporta:page(tamaño + márgenes en mm), cadenasheader/footer,footer_page_numbers(añade un campo de pie "Página X de Y"),styles(estilos de párrafo personalizados con fuente, tamaño, negrita/cursiva,colorhex), yblocks—heading(nivel 1-9),paragraph(o bientexto una listarunsdonde cada ejecución puede establecerbold/italic/underline),bullet_list,numbered_list,table(filaheaderrenderizada en negrita,rows, opcionalstylede tabla incorporado comoTable Grid),image(path, opcionalwidth_mm),toc(campo de Tabla de Contenido) ypage_break. El formato completo de la especificación está documentado al principio descripts/docx_create.py. - Leer. Usa
scripts/docx_read.pycon exactamente una bandera de modo.--textdevuelve párrafos del cuerpo, todo el texto de las celdas de la tabla y texto de encabezado/pie como JSON.--structuredevuelve el esquema de títulos más recuentos de párrafos/tablas/secciones.--images DIRcopia cada archivo bajoword/media/fuera del paquete. - Editar. Usa
scripts/docx_edit.py.replacerecorre el cuerpo, tablas (incluidas las anidadas), encabezados y pies de página, y conserva el formato de las ejecuciones; añade--body-onlypara omitir encabezados/pies. Pasa-o out.docxpara mantener el original; omítelo para editar en el lugar. Los índices de párrafo parainsert/delete/style/tocse refieren al orden del cuerpo de--structure/--text. Ejecutanormalizeprimero en documentos que han pasado por una edición intensa de Word: fusiona ejecuciones adyacentes con formato idéntico para que la búsqueda-reemplazo posterior coincida de forma fiable. - Revisar revisiones.
docx_revisions.py listinforma cadaw:insyw:del(id, autor, fecha, texto afectado) en cualquier parte del cuerpo, tablas, encabezados o pies.accept-all/reject-alllos resuelve en bloque;accept/reject --id Nmaneja una sola revisión. Aceptar conserva las inserciones y elimina el texto eliminado; rechazar hace lo contrario. - Comentarios.
docx_comments.py listdevuelve el id, autor, fecha, texto del cuerpo y el texto del documento al que está anclado cada comentario.add --target "alguna frase"ancla un nuevo comentario a la primera aparición de esa frase (las ejecuciones se dividen según sea necesario; el formato se conserva).delete --id Nelimina el comentario y sus marcadores sin tocar el texto del documento. - Plantilla. Coloca tokens del estilo
{{name}}en el documento. Ejecutascripts/docx_template.pycon un objeto JSON de valores. Usa--strictpara fallar cuando queden tokens sin rellenar; la salida JSON lista recuentosfilledyunfilled_tokensde cualquier manera. - Verificar (siempre): vuelve a leer la salida con
--texto--structure, y ejecutadocx_validate.pyen todo lo que hayas producido mediante manipulación de revisiones/comentarios.
Conversión a PDF
No se necesita script. Cuando LibreOffice está instalado, convierte sin interfaz:
soffice --headless --convert-to pdf --outdir outdir/ file.docx
Comprueba primero la disponibilidad (command -v soffice || command -v libreoffice). Si ninguno existe, informa al usuario de que la conversión a PDF no
está disponible en este entorno en lugar de improvisar — python-docx no puede
renderizar PDFs, y la fidelidad del diseño requiere un renderizador real.
Errores Comunes
- Tokens divididos entre ejecuciones. Word a menudo fragmenta el texto en varias
ejecuciones. Los ayudantes de reemplazo colapsan las ejecuciones coincidentes (el
reemplazo hereda el formato de la primera ejecución); ejecutar
docx_edit.py normalizeprimero reduce la fragmentación para todas las ediciones posteriores. - Cobertura de revisiones.
docx_revisions.pyresuelve inserciones y eliminaciones a nivel de ejecución (la gran mayoría). Las revisiones de marcas de párrafo y filas de tabla, los registros de cambio de formato y los movimientos son detectados por--revisionspero no resueltos automáticamente — consultareferences/revisions-and-comments.mdy pásalos a Word. - Hilo de comentarios. Las respuestas y el estado "resuelto" viven en
commentsExtended.xml, que esta habilidad ignora; los comentarios que añade son comentarios simples de nivel superior. - Los resultados de campo son calculados por Word.
toc,page-numbersy las opciones de especificacióntoc/footer_page_numbersescriben códigos de campo. Word/LibreOffice completa las entradas reales y los números cuando se abre el archivo (Word puede solicitar actualizar campos); python-docx nunca los calcula, por lo que se muestra texto de marcador de posición hasta entonces. - La validación es una comprobación de integridad, no una validación de esquema.
docx_validate.pyverifica el zip, las partes requeridas, los destinos de las relaciones, los bytes mágicos de la imagen y los estilos referenciados. NO es validación XSD — un archivo puede pasarla y aun así contener XML que Word no admite. - Los nombres de estilo deben existir. Aplicar un estilo que no está definido en el
documento genera
KeyError. Los estilos integrados comoHeading 1,List Bullet,List Number,Table Gridexisten en la plantilla predeterminada; los estilos personalizados deben declararse primero en la especificación de creación. - Las listas numeradas se reinician.
List Numberdepende de la numeración predeterminada de Word; las listas separadas en un mismo documento pueden continuar la numeración en lugar de reiniciarse. Advierte a los usuarios que necesiten una numeración precisa de varias listas. - Las escrituras en celdas reemplazan el formato.
set-cellusacell.text = ..., lo que reinicia las ejecuciones en esa celda a formato simple. - Codificación. Todos los archivos de especificación/valores JSON se leen explícitamente como UTF-8; nunca confíes en los valores predeterminados de la configuración regional al escribir tu propio código de conexión.
- No descomprimas y uses sed en el XML. Edita a través de los scripts (o
python-docx); la sustitución de texto sin formato en
document.xmlcorrompe archivos fácilmente. Usapatch/write_filesolo para las entradas JSON, nunca en el propio.docx.
Verificación
- Después de crear/editar/plantilla, ejecuta
docx_read.py out.docx --texty comprueba que aparecen las cadenas esperadas (y que las cadenas antiguas han desaparecido). - Después de aceptar/rechazar,
docx_revisions.py listdebe devolver[](o solo los ids que dejaste intencionadamente); después de la manipulación de comentarios,docx_comments.py listdebe reflejar el cambio y la salida--textdebe permanecer sin cambios. docx_validate.py out.docxsale con 0 y"ok": trueen un paquete saludable — ejecútalo después de cualquier manipulación de revisión/comentario/campo.- Para plantillas ejecutadas con
--strict, o comprueba queunfilled_tokens == []. - Comprobaciones de estructura:
--structuredebe mostrar el esquema de títulos esperado y las formas de las tablas;--stylesconfirma que se aplicaron los estilos personalizados.