Communitygithub.com

V4TIME/V4SKILL

Créer, lire, fusionner, remplir, OCRiser et éditer du texte dans des fichiers PDF.

Qu'est-ce que V4SKILL ?

Cette compétence offre un ensemble complet d'outils en ligne de commande (Python) pour manipuler des fichiers PDF : création à partir de spécifications JSON structurées, extraction de texte, de tableaux et de métadonnées, fusion, scission, rotation, filigrane et impression. Elle permet également de construire et remplir des formulaires AcroForm interactifs, de gérer les métadonnées et les pièces jointes, et d'appliquer un chiffrement/déchiffrement (AES-256). Pour les PDF numérisés (pages image uniquement), la compétence redirige vers des scripts d'OCR dédiés (pymupdf, marker-pdf). Elle est conçue pour fonctionner sur tout terminal Python avec les bibliothèques pypdf, reportlab, pdfplumber et pypdfium2 (ou pdftoppm pour le rendu d'images). L'utilisateur exécute des scripts individuels (scripts/pdf_*.py) avec des arguments en ligne de commande, chaque script produisant une sortie JSON structurée et un code de retour non nul en cas d'échec. La compétence insiste sur l'inspection préalable des PDF (vérification du chiffrement, présence de texte), la validation visuelle des formulaires et le respect des limites des bibliothèques (aplatissement des formulaires, extraction heuristique des tableaux, compression partielle). Elle prend en charge les plateformes Claude Code, Cursor, Codex et tout environnement où ces scripts peuvent être exécutés.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/productivity/pdf

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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's pdftoppm dans 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âcheOutilCommande / API
Créer un document (titres, tableaux, images)reportlab platypuspdf_create.py spec.json -o out.pdf
Construire un formulaire remplissablereportlab acroFormpdf_make_form.py formspec.json -o form.pdf
Vérifier la mise en page / image de superpositionpython pur + PILpdf_form_layout.py formspec.json [--render-overlay o.png]
Texte par pagepdfplumberpdf_read.py f.pdf --text
Tableaux → JSON/CSVpdfplumberpdf_read.py f.pdf --tables
Métadonnées / tailles / chiffré / numérisépypdf + pdfplumberpdf_read.py f.pdf --meta
Fusionner (+ plan)pypdfpdf_merge.py a.pdf b.pdf -o m.pdf
Scinder / extraire / rotaterpypdfpdf_split.py f.pdf --pages 2-5 --rotate 90
Lister / remplir / aplatir un formulairepypdfpdf_read.py --fields, pdf_fill_form.py
Chiffrer / déchiffrer (AES-256)pypdfpdf_secure.py --encrypt/--decrypt
Filigraner / tamponner une page PDFpypdfpdf_watermark.py f.pdf --stamp w.pdf
Tamponner du texte/une image à des coordonnéesreportlab + pypdfpdf_stamp.py f.pdf --text "Signez ici" --x 400 --y 60
Pages → PNG (revue / transfert OCR)pypdfium2 ou pdftoppmpdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/
Définir/effacer les métadonnées, pièces jointespypdfpdf_meta.py --set-meta / --attach / --extract-attachments
Compresser les flux de contenupypdfpdf_split.py f.pdf --pages 1-N --compress

Procédure

  1. Inspecter d'abord. Exécutez pdf_read.py file.pdf --meta. Vérifiez encrypted (si vrai, déchiffrez d'abord avec pdf_secure.py --decrypt) et likely_scanned_pages. Si les pages sont uniquement des images, exportez-les avec pdf_page_image.py --pages <numérisées> --dpi 300 --out-dir imgs/ et confiez les PNG à la compétence references/ocr-extraction.md — ne rapportez pas de texte vide comme "pas de contenu".
  2. Créer. Écrivez une spécification JSON avec write_file (éléments : heading, paragraph, table, image, pagebreak ; métadonnées optionnelles title/author ; les numéros de page sont ajoutés automatiquement), puis exécutez pdf_create.py. Vérifiez visuellement avec vision_analyze sur une image de page rendue si la mise en page est importante.
  3. Extraire. --text donne une liste JSON de chaînes par page ; --tables donne des tableaux de lignes par page et peut également émettre des fichiers CSV. Lisez les résultats avec read_file ; ne regardez jamais un PDF binaire directement.
  4. Manipuler. pdf_merge.py concatène et peut ajouter un signet par fichier source ; pdf_split.py gè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. via pdf_create.py) et en le superposant avec pdf_watermark.py ; pour des tampons en une ligne ("signer ici", BROUILLON en diagonale, étiquettes de coin), utilisez pdf_stamp.py avec du texte ou une image à des coordonnées explicites.
  5. Construire des formulaires. Écrivez une spécification JSON de formulaire (champs avec label_box/entry_box en points PDF — voir references/forms.md), vérifiez-la avec pdf_form_layout.py et corrigez chaque problème signalé, examinez éventuellement le PNG --render-overlay avec vision_analyze, puis construisez avec pdf_make_form.py et confirmez avec pdf_read.py --fields.
  6. Remplir des formulaires. Listez les champs (--fields) pour connaître les noms et types exacts, écrivez un JSON UTF-8 de {"NomChamp": "valeur"} avec write_file (les cases à cocher acceptent true/false ; les valeurs des boutons radio/listes déroulantes doivent correspondre aux options d'exportation du champ), puis pdf_fill_form.py. Relisez avec --fields pour confirmer que les valeurs sont bien placées.
  7. Métadonnées et pièces jointes. pdf_meta.py --set-meta écrit le Titre/Auteur/Sujet/Mots-clés (DocInfo) ; --clear-meta les supprime ; --attach/--list-attachments/--extract-attachments gèrent les fichiers intégrés.
  8. 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.
  9. 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 vers references/ocr-extraction.md ; n'inventez pas de texte.
  • Limites de l'aplatissement : pdf_fill_form.py --flatten utilise 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 avec vision_analyze ; pour un aplatissement infaillible, utilisez un moteur de rendu externe (ex. Ghostscript ou pdftoppm+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 NeedAppearances du 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 : --compress ne 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_settings ou 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 — voir references/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.pdf avec 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 — confirmez page_count et rotation par 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.json doit sortir avec le code 0 ; puis --render-overlay boxes.png --pdf form.pdf et examinez le PNG avec vision_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 --fields liste 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 --fields et 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.py et inspectez avec vision_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 : --meta affiche "encrypted": true et 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.

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

Skills associés