Compétence Docx
Créer, lire, éditer et générer à partir de modèles des fichiers Microsoft Word .docx avec
python-docx via de petites CLI. Elle gère le texte, les styles, les listes, les tableaux,
les images, les en-têtes/pieds de page, le templating {{token}}, les révisions
(lister/accepter/rejeter), les commentaires (lister/ajouter/supprimer), les champs TdM et de
numérotation de pages, et les vérifications d'intégrité. Elle ne rend pas elle-même les documents
(PDF nécessite LibreOffice — voir Conversion en PDF) et ne modifie pas le format .doc hérité.
Quand l'utiliser
- L'utilisateur demande de générer un document Word (rapport, lettre, contrat).
- Vous avez besoin du texte, du plan, des styles ou des images intégrées d'un
.docx. - Vous devez modifier un
.docxexistant : remplacer du texte, modifier des cellules de tableau, insérer/supprimer des paragraphes, appliquer des styles, fusionner des fragments de texte. - Vous avez un modèle
.docxavec des{{placeholders}}à remplir à partir de données. - Le document comporte des révisions (suivi des modifications) à examiner, accepter ou rejeter.
- Vous devez lire les commentaires des relecteurs, ou ajouter/supprimer des commentaires.
- Un
.docxne s'ouvre pas ou se comporte étrangement et vous devez diagnostiquer une corruption. - Le document a besoin d'une table des matières ou de pieds de page « Page X sur Y ».
- Ne convient pas pour :
.doc(hérité),.odtou travail de mise en page WYSIWYG.
Prérequis
- Python 3.10+ avec
python-docxinstallé :pip install python-docx(le nom d'importation estdocx; lxml est inclus). - Les commentaires
addutilisent l'API native sur python-docx >= 1.2 et une solution de repli XML sur les versions plus anciennes — les deux sont automatiques. - Pour les blocs d'image : les fichiers image doivent exister localement (PNG/JPEG).
Comment exécuter
Tous les scripts se trouvent dans scripts/ à côté de ce fichier. Exécutez-les avec
l'outil terminal ; chacun prend en charge --help et affiche du JSON sur 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
Référence rapide
| Tâche | Commande |
|---|---|
| Créer à partir d'une spécification JSON | docx_create.py spec.json out.docx |
| Texte intégral (corps+tableaux+en-têtes/pieds) | docx_read.py f.docx --text |
| Plan des titres + formes des tableaux | docx_read.py f.docx --structure |
| Styles réellement utilisés | docx_read.py f.docx --styles |
| Extraire les images intégrées | docx_read.py f.docx --images outdir/ |
| Détecter les révisions/commentaires | docx_read.py f.docx --revisions |
| Rechercher/remplacer (formatage conservé) | docx_edit.py replace f.docx --find A --replace B -o out.docx |
| Définir une cellule de tableau | docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X |
| Insérer un paragraphe avant l'index N | docx_edit.py insert f.docx --index N --text X --style Normal |
| Supprimer le paragraphe N | docx_edit.py delete f.docx --index N |
| Appliquer un style au paragraphe N | docx_edit.py style f.docx --index N --style "Heading 1" |
| Fusionner les fragments adjacents de même format | docx_edit.py normalize f.docx -o out.docx |
| Insérer un champ TdM avant le para N | docx_edit.py toc f.docx --index N -o out.docx |
| Pieds de page « Page X sur Y » | docx_edit.py page-numbers f.docx |
Remplir {{tokens}} | docx_template.py tpl.docx values.json out.docx --strict |
| Lister les révisions (id/auteur/date/texte) | docx_revisions.py list f.docx |
| Accepter / Rejeter toutes les révisions | docx_revisions.py accept-all f.docx -o out.docx (ou reject-all) |
| Accepter / Rejeter une révision | docx_revisions.py accept f.docx --id 3 -o out.docx |
| Lister les commentaires (+texte ancré) | docx_comments.py list f.docx |
| Ajouter un commentaire ancré à du texte | docx_comments.py add f.docx --target "phrase" --text "note" --author You |
| Supprimer un commentaire par id | docx_comments.py delete f.docx --id 0 |
| Vérifier l'intégrité du package | docx_validate.py f.docx (sortie 1 en cas d'erreur) |
Procédure
- Créer. Rédigez une spécification JSON avec
write_file, puis exécutezscripts/docx_create.py. La spécification prend en charge :page(taille + marges en mm), chaînesheader/footer,footer_page_numbers(ajoute un champ de pied de page « Page X sur Y »),styles(styles de paragraphe personnalisés avec police, taille, gras/italique, couleur hexadécimalecolor), etblocks—heading(niveau 1-9),paragraph(soittextsoit une listerunsoù chaque passage peut définirbold/italic/underline),bullet_list,numbered_list,table(ligne d'headerrendue en gras,rows, style de tableau intégré optionnel tel queTable Grid),image(path,width_mmoptionnel),toc(champ de table des matières), etpage_break. Le format complet de la spécification est documenté en haut descripts/docx_create.py. - Lire. Utilisez
scripts/docx_read.pyavec exactement un indicateur de mode.--textrenvoie les paragraphes du corps, tout le texte des cellules de tableau et le texte des en-têtes/pieds de page au format JSON.--structurerenvoie le plan des titres plus le nombre de paragraphes/tableaux/sections.--images DIRcopie tous les fichiers sousword/media/hors du package. - Éditer. Utilisez
scripts/docx_edit.py.replaceparcourt le corps, les tableaux (imbriqués inclus), les en-têtes et les pieds de page, et préserve le formatage des passages ; ajoutez--body-onlypour ignorer les en-têtes/pieds de page. Utilisez-o out.docxpour conserver l'original ; omettez-le pour modifier sur place. Les index de paragraphe pourinsert/delete/style/tocse réfèrent à l'ordre du corps de--structure/--text. Lanceznormalized'abord sur les documents issus d'une édition Word intensive — il fusionne les passages adjacents avec un formatage identique afin que les recherches/remplacements ultérieurs correspondent de manière fiable. - Réviser les révisions.
docx_revisions.py listsignale chaquew:insetw:del(id, auteur, date, texte affecté) partout dans le corps, les tableaux, les en-têtes ou les pieds de page.accept-all/reject-allles résolvent en masse ;accept/reject --id Ngère une seule révision. Accepter conserve les insertions et supprime le texte supprimé ; rejeter fait l'inverse. - Commentaires.
docx_comments.py listrenvoie pour chaque commentaire son id, auteur, date, texte du corps, et le texte du document auquel il est ancré.add --target "une phrase"ancre un nouveau commentaire à la première occurrence de cette phrase (les passages sont divisés si nécessaire ; le formatage est conservé).delete --id Nsupprime le commentaire et ses marqueurs sans toucher au texte du document. - Modèle. Placez des jetons de style
{{nom}}dans le document. Lancezscripts/docx_template.pyavec un objet JSON de valeurs. Utilisez--strictpour échouer lorsque des jetons restent non remplis ; la sortie JSON liste les comptesfilledetunfilled_tokensdans les deux cas. - Vérifier (toujours) : relisez la sortie avec
--textou--structure, et exécutezdocx_validate.pysur tout ce que vous avez produit via une intervention sur les révisions/commentaires.
Conversion en PDF
Aucun script nécessaire. Lorsque LibreOffice est installé, convertissez sans interface :
soffice --headless --convert-to pdf --outdir outdir/ file.docx
Vérifiez d'abord la disponibilité (command -v soffice || command -v libreoffice). Si aucun des deux n'existe, dites à l'utilisateur que la conversion PDF est
indisponible dans cet environnement plutôt que de bricoler — python-docx ne peut pas
rendre les PDF, et la fidélité de mise en page nécessite un moteur de rendu réel.
Pièges à éviter
- Jetons fragmentés entre passages. Word fragmente souvent le texte en plusieurs
passages. Les scripts de remplacement regroupent les passages correspondants (le remplacement hérite
du formatage du premier passage) ; l'exécution de
docx_edit.py normalizeen premier réduit la fragmentation pour toutes les modifications ultérieures. - Couverture des révisions.
docx_revisions.pyrésout les insertions et suppressions au niveau des passages (l'écrasante majorité). Les révisions de marques de paragraphe et de lignes de tableau, les enregistrements de changement de format et les déplacements sont détectés par--revisionsmais pas résolus automatiquement — voirreferences/revisions-and-comments.mdet transmettez-les à Word. - Threads de commentaires. Les réponses et le statut « résolu » vivent dans
commentsExtended.xml, que cette compétence ignore ; les commentaires qu'elle ajoute sont des commentaires simples de premier niveau. - Les résultats des champs sont calculés par Word.
toc,page-numberset les options de spécificationtoc/footer_page_numbersécrivent des codes de champ. Word/LibreOffice peuple les entrées et numéros réels lorsque le fichier est ouvert (Word peut demander à mettre à jour les champs) ; python-docx ne les calcule jamais, donc un texte de remplacement s'affiche jusqu'à ce moment. - La validation est une vérification d'intégrité, pas une validation de schéma.
docx_validate.pyvérifie le zip, les parties requises, les cibles des relations, les octets magiques des images et les styles référencés. Ce n'est PAS une validation XSD — un fichier peut réussir et contenir du XML que Word n'aime pas. - Les noms de styles doivent exister. Appliquer un style qui n'est pas défini dans le
document lève
KeyError. Les styles intégrés commeHeading 1,List Bullet,List Number,Table Gridexistent dans le modèle par défaut ; les styles personnalisés doivent d'abord être déclarés dans la spécification de création. - Les listes numérotées redémarrent.
List Numberrepose sur la numérotation par défaut de Word ; des listes séparées dans un même document peuvent continuer la numérotation au lieu de redémarrer. Avertissez les utilisateurs ayant besoin d'une numérotation précise pour plusieurs listes. - Les écritures dans les cellules remplacent le formatage.
set-cellutilisecell.text = ..., ce qui réinitialise les passages dans cette cellule à un formatage simple. - Encodage. Tous les fichiers de spécifications/valeurs JSON sont lus explicitement en UTF-8 ; ne vous fiez jamais aux valeurs par défaut de la locale lorsque vous écrivez votre propre code de liaison.
- Ne dézippez pas et n'utilisez pas sed sur le XML. Modifiez via les scripts (ou
python-docx) ; une substitution de texte brut dans
document.xmlcorrompt facilement les fichiers. Utilisezpatch/write_fileuniquement pour les entrées JSON, jamais sur le fichier.docxlui-même.
Vérification
- Après création/édition/modèle, exécutez
docx_read.py out.docx --textet vérifiez que les chaînes attendues apparaissent (et que les anciennes chaînes ont disparu). - Après acceptation/rejet,
docx_revisions.py listdevrait retourner[](ou seulement les identifiants que vous avez intentionnellement laissés) ; après une intervention sur les commentaires,docx_comments.py listdevrait refléter le changement et la sortie--textdoit être inchangée. docx_validate.py out.docxsort 0 avec"ok" : truesur un package sain — exécutez-le après toute manipulation de révisions/commentaires/champs.- Pour les modèles exécutés avec
--strict, ou vérifiez queunfilled_tokens == []. - Vérifications de structure :
--structuredevrait montrer le plan de titres attendu et les formes des tableaux ;--stylesconfirme que les styles personnalisés ont été appliqués.