Compétence PDF
Créez des PDF à partir de spécifications structurées, construisez et remplissez des formulaires AcroForm (avec vérification de la mise en page et superpositions visuelles), extrayez texte/tableaux/métadonnées, fusionnez/scindez/rotations/filigrane/tamponnez des pages, exportez des pages en images, gérez les métadonnées et les pièces jointes, et chiffrez/déchiffrez — en utilisant pypdf, reportlab et pdfplumber. Deux capacités annexes se trouvent dans references/ (lisez le fichier correspondant avant ces tâches) :
- PDF numérisés/images uniquement et OCR (chemin rapide pymupdf, chemin qualité marker-pdf, scripts/extract_pymupdf.py + scripts/extract_marker.py) :
references/ocr-extraction.md - Édition de texte dans un PDF existant via des invites en langage naturel (CLI nano-pdf) :
references/nano-pdf-editing.md
Quand l'utiliser
- Générer un rapport, une facture ou un document multipage en PDF.
- Construire un formulaire AcroForm remplissable (texte/case à cocher/bouton radio/liste déroulante) à partir d'une spécification JSON, en vérifiant d'abord la mise en page.
- Extraire du texte, des tableaux (JSON/CSV), des métadonnées ou les valeurs de champs de formulaire d'un PDF.
- Fusionner, scinder, rotater, extraire des sous-ensembles de pages, filigraner, tamponner du texte/des images à des coordonnées, ajouter des signets ou compresser des PDF.
- Exporter des pages en PNG pour une revue visuelle ou pour confier à l'OCR ; définir/effacer les métadonnées du document ; ajouter/extraire des pièces jointes.
- Remplir ou aplatir des formulaires AcroForm ; chiffrer ou déchiffrer avec des mots de passe.
- NE PAS utiliser pour les PDF numérisés/images uniquement (utilisez
references/ocr-extraction.md) et NE PAS utiliser pour le rendu HTML-à-PDF pixel-perfect (utilisez un navigateur sans tête).
Prérequis
- Python 3.10+ avec
pypdf,reportlab,pdfplumber:python -m pip install pypdf reportlab pdfplumber - Optionnel, pour la pixellisation de pages (
pdf_page_image.py, rendu de superposition) :python -m pip install pypdfium2, ou poppler'spdftoppmdans le PATH. Les scripts utilisent pypdfium2 → pdftoppm en ordre de repli et rapportent{"rendered": false, "missing": [...]}(code de sortie 0) quand aucun n'est présent. - Chaque script d'aide vérifie les importations paresseusement et affiche une astuce d'installation si une dépendance est manquante.
Comment exécuter
Tous les helpers se trouvent dans scripts/ et sont des CLI argparse — exécutez-les avec l'outil terminal ; chacun supporte --help. Ils lisent/écrivent du JSON strictement en UTF-8, impriment les résultats JSON sur stdout et sortent avec un code non nul en cas d'échec.
python scripts/pdf_create.py spec.json -o out.pdf # créer un PDF à partir d'une spécification JSON
python scripts/pdf_make_form.py formspec.json -o form.pdf # créer un formulaire AcroForm remplissable à partir d'une spécification JSON
python scripts/pdf_form_layout.py formspec.json # vérifier la mise en page du formulaire AVANT de le construire
python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
python scripts/pdf_read.py doc.pdf --text # texte par page (JSON)
python scripts/pdf_read.py doc.pdf --tables --csv-dir t/ # tableaux vers des fichiers JSON + CSV
python scripts/pdf_read.py doc.pdf --meta # métadonnées, tailles de pages, indicateurs chiffré/numérisé
python scripts/pdf_read.py form.pdf --fields # champs de formulaire : nom, type, valeur
python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]
python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]
python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]
python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password
python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password
python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "BROUILLON" --x 150 --y 400 \
--font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120
python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/
python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf
python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf
python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/
Référence rapide
| Tâche | Outil | Commande / API |
|---|---|---|
| Créer un document (titres, tableaux, images) | reportlab platypus | pdf_create.py spec.json -o out.pdf |
| Construire un formulaire remplissable | reportlab acroForm | pdf_make_form.py formspec.json -o form.pdf |
| Vérifier la mise en page / image de superposition | python pur + PIL | pdf_form_layout.py formspec.json [--render-overlay o.png] |
| Texte par page | pdfplumber | pdf_read.py f.pdf --text |
| Tableaux → JSON/CSV | pdfplumber | pdf_read.py f.pdf --tables |
| Métadonnées / tailles / chiffré / numérisé | pypdf + pdfplumber | pdf_read.py f.pdf --meta |
| Fusionner (+ plan) | pypdf | pdf_merge.py a.pdf b.pdf -o m.pdf |
| Scinder / extraire / rotater | pypdf | pdf_split.py f.pdf --pages 2-5 --rotate 90 |
| Lister / remplir / aplatir un formulaire | pypdf | pdf_read.py --fields, pdf_fill_form.py |
| Chiffrer / déchiffrer (AES-256) | pypdf | pdf_secure.py --encrypt/--decrypt |
| Filigraner / tamponner une page PDF | pypdf | pdf_watermark.py f.pdf --stamp w.pdf |
| Tamponner du texte/une image à des coordonnées | reportlab + pypdf | pdf_stamp.py f.pdf --text "Signez ici" --x 400 --y 60 |
| Pages → PNG (revue / transfert OCR) | pypdfium2 ou pdftoppm | pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/ |
| Définir/effacer les métadonnées, pièces jointes | pypdf | pdf_meta.py --set-meta / --attach / --extract-attachments |
| Compresser les flux de contenu | pypdf | pdf_split.py f.pdf --pages 1-N --compress |
Procédure
- Inspecter d'abord. Exécutez
pdf_read.py file.pdf --meta. Vérifiezencrypted(si vrai, déchiffrez d'abord avecpdf_secure.py --decrypt) etlikely_scanned_pages. Si les pages sont uniquement des images, exportez-les avecpdf_page_image.py --pages <numérisées> --dpi 300 --out-dir imgs/et confiez les PNG à la compétencereferences/ocr-extraction.md— ne rapportez pas de texte vide comme "pas de contenu". - Créer. Écrivez une spécification JSON avec
write_file(éléments :heading,paragraph,table,image,pagebreak; métadonnées optionnellestitle/author; les numéros de page sont ajoutés automatiquement), puis exécutezpdf_create.py. Vérifiez visuellement avecvision_analyzesur une image de page rendue si la mise en page est importante. - Extraire.
--textdonne une liste JSON de chaînes par page ;--tablesdonne des tableaux de lignes par page et peut également émettre des fichiers CSV. Lisez les résultats avecread_file; ne regardez jamais un PDF binaire directement. - Manipuler.
pdf_merge.pyconcatène et peut ajouter un signet par fichier source ;pdf_split.pygère les plages de pages (basé sur 1, ex.1-3,5,9-), la rotation par pas de 90° et--compress. Filigrane en préparant un PDF tampon d'une seule page (ex. viapdf_create.py) et en le superposant avecpdf_watermark.py; pour des tampons en une ligne ("signer ici", BROUILLON en diagonale, étiquettes de coin), utilisezpdf_stamp.pyavec du texte ou une image à des coordonnées explicites. - Construire des formulaires. Écrivez une spécification JSON de formulaire (champs avec
label_box/entry_boxen points PDF — voirreferences/forms.md), vérifiez-la avecpdf_form_layout.pyet corrigez chaque problème signalé, examinez éventuellement le PNG--render-overlayavecvision_analyze, puis construisez avecpdf_make_form.pyet confirmez avecpdf_read.py --fields. - Remplir des formulaires. Listez les champs (
--fields) pour connaître les noms et types exacts, écrivez un JSON UTF-8 de{"NomChamp": "valeur"}avecwrite_file(les cases à cocher acceptenttrue/false; les valeurs des boutons radio/listes déroulantes doivent correspondre aux options d'exportation du champ), puispdf_fill_form.py. Relisez avec--fieldspour confirmer que les valeurs sont bien placées. - Métadonnées et pièces jointes.
pdf_meta.py --set-metaécrit le Titre/Auteur/Sujet/Mots-clés (DocInfo) ;--clear-metales supprime ;--attach/--list-attachments/--extract-attachmentsgèrent les fichiers intégrés. - Sécuriser. Chiffrez avec des mots de passe utilisateur/propriétaire distincts et AES-256. Pour supprimer un mot de passe connu,
--decryptécrit une copie non chiffrée. - Vérifier (voir ci-dessous) avant de signaler le succès.
Pièges
- PDF numérisés :
extract_text()vide plus des pages image signifie qu'il n'y a pas de couche de texte. Redirigez versreferences/ocr-extraction.md; n'inventez pas de texte. - Limites de l'aplatissement :
pdf_fill_form.py --flattenutilise le support d'aplatissement de pypdf, qui convertit les apparences de widget en contenu de page. Il est fiable pour les champs de texte simples et les cases à cocher, mais peut supprimer ou mal rendre les widgets exotiques (texte enrichi, flux d'apparence personnalisés, certains groupes de boutons radio). Vérifiez la sortie aplatie visuellement avecvision_analyze; pour un aplatissement infaillible, utilisez un moteur de rendu externe (ex. Ghostscript oupdftoppm+réassemblage) comme solution de repli. - NeedAppearances : après le remplissage, les visualiseurs ne rendent les valeurs que si les flux d'apparence existent. Le script de remplissage définit le drapeau
NeedAppearancesdu formulaire AcroForm afin que les visualiseurs conformes les régénèrent ; certains visualiseurs minimaux l'ignorent — aplatissez si la fidélité d'affichage est importante. - Valeurs de formulaire non latines : les valeurs sont stockées correctement (UTF-16), mais la police par défaut du champ peut manquer de glyphes, donc un visualiseur peut afficher des blancs même si les données sont bien présentes. Vérifiez avec
--fields, pas seulement visuellement. - Attentes de compression :
--compressne dégonfle que les flux de contenu. Les économies typiques sont de 0 à 20 % ; cela ne fait rien pour les PDF dominés par des images ou des flux déjà compressés. Ce n'est pas un substitut au sous-échantillonnage d'image (domaine de Ghostscript). - Les drapeaux de permission ne s'appliquent pas : les bits de permission du mot de passe propriétaire (pas d'impression, pas de copie) sont des demandes polies que les visualiseurs peuvent respecter ; toute bibliothèque (y compris pypdf) peut les lire et les supprimer. Seul le mot de passe utilisateur verrouille réellement le contenu via le chiffrement. Ne présentez jamais les drapeaux de permission comme une sécurité.
- L'extraction de tableaux est heuristique : pdfplumber détecte les tableaux à partir des lignes de séparation/alignement des mots ; les tableaux sans bordures ou avec cellules fusionnées peuvent nécessiter un réglage de
table_settingsou un nettoyage manuel. - Indexation des pages : les CLI helpers prennent des pages basées sur 1 ; les API pypdf sont basées sur 0. Les scripts effectuent la conversion — ne doublez pas la conversion.
- Extraction de texte de tampon roté : le regroupement de lignes de pdfplumber brouille les glyphes rotés (un "BROUILLON" à 45° s'extrait comme des lettres éparpillées) ; vérifiez les tampons rotés avec
extract_text()de pypdf ou une image rendue à la place. - Groupes de boutons radio : reportlab a besoin de ≥2 widgets
radio()par groupe, les remplissages ont besoin de la valeur d'exportation avec barre oblique ("/red"), et la fidélité de l'aplatissement est la pire pour les boutons radio — voirreferences/forms.md. - Portée des métadonnées :
pdf_meta.pyécrit uniquement le dictionnaire DocInfo classique ; les métadonnées XMP intégrées (si présentes) sont laissées intactes et peuvent afficher des valeurs différentes dans certains visualiseurs. - PDF/A est hors de portée : pypdf/reportlab ne peuvent pas produire ou valider des PDF/A conformes. Si la conformité archivistique est requise, exécutez Ghostscript via l'outil
terminal(ex.gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdfavec un profil ICC approprié) et validez avec veraPDF — les deux sont des installations externes, et le résultat nécessite toujours une validation, pas une supposition. - La rotation doit être un multiple de 90 ; les entrées chiffrées doivent être déchiffrées avant toute autre opération.
Vérification
- Après création/fusion/scission :
pdf_read.py out.pdf --meta— confirmezpage_countetrotationpar page lorsque vous avez effectué une rotation. - Après extraction : vérifiez que le JSON n'est pas vide et faites un test ponctuel sur une chaîne ou une cellule connue.
- Boucle de conception de formulaire :
pdf_form_layout.py spec.jsondoit sortir avec le code 0 ; puis--render-overlay boxes.png --pdf form.pdfet examinez le PNG avecvision_analyze(rouge = zones de saisie avec noms de champs, bleu = zones d'étiquette) en recherchant les chevauchements, les désalignements et les étiquettes détachées de leurs champs. Itérez spécification → vérification → superposition jusqu'à ce que ce soit propre. - Après la construction d'un formulaire :
pdf_read.py form.pdf --fieldsliste chaque champ de la spécification avec le bon type et les bonnes options. - Après le remplissage d'un formulaire :
pdf_read.py filled.pdf --fieldset comparez les valeurs (correspondance exacte, y compris les caractères non ASCII). - Après le tamponnage : réextrayez le texte (pypdf pour les tampons rotés) ou rendez la page avec
pdf_page_image.pyet inspectez avecvision_analyze. - Après les modifications de métadonnées/pièces jointes :
pdf_read.py --meta/pdf_meta.py --list-attachments, et réextrayez une pièce jointe pour comparer les octets. - Après chiffrement :
--metaaffiche"encrypted": trueet l'ouverture sans mot de passe échoue ; après déchiffrement, l'extraction de texte correspond à l'original. - Pour tout ce qui est visuel (filigranes, formulaires aplatis), rendez et inspectez avec
vision_analyze.