alran 0.0.0-stage → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ALRAN_TOOLS_NOTICES.md +64 -0
- package/LICENSE +27 -0
- package/LICENSE-STATUS.md +21 -0
- package/NOTICE +6 -0
- package/README.md +289 -2
- package/THIRD_PARTY_NOTICES.md +113 -0
- package/alran-tools.js +3 -0
- package/assets/agents/_default/prompt-auto_classifier.md +185 -0
- package/assets/agents/_default/prompt-auto_classifier_extras.md +17 -0
- package/assets/agents/_default/prompt-base-all.md +133 -0
- package/assets/agents/_default/prompt-base-all.md.hbs +228 -0
- package/assets/agents/_default/prompt-base-windows.md +5 -0
- package/assets/agents/_default/prompt-base-windows.md.hbs +5 -0
- package/assets/agents/_default/prompt-base-worker.md +10 -0
- package/assets/agents/_default/prompt-base-worker.md.hbs +27 -0
- package/assets/agents/_default/prompt-compact.md +76 -0
- package/assets/agents/_default/prompt-compact_continue.md +9 -0
- package/assets/agents/_default/prompt-git.md +8 -0
- package/assets/agents/_default/prompt-goal.md +13 -0
- package/assets/agents/_default/prompt-session-branch.md +3 -0
- package/assets/agents/_default/prompt-session-branch.md.hbs +30 -0
- package/assets/agents/_default/prompt-session-root.md +3 -0
- package/assets/agents/_default/prompt-session-root.md.hbs +32 -0
- package/assets/agents/_default/prompt-title.md +11 -0
- package/assets/agents/_default/prompt-tool_agent.md +22 -0
- package/assets/agents/_migration/README.md +20 -0
- package/assets/agents/_migration/coder/PERSONA.md +11 -0
- package/assets/agents/_migration/coder/system-prompt.md.hbs +42 -0
- package/assets/agents/_migration/general/PERSONA.md +11 -0
- package/assets/agents/_migration/general/system-prompt.md.hbs +49 -0
- package/assets/agents/_v2/AGENT_CONTEXT.md.hbs +245 -0
- package/assets/agents/_v2/PTC_TOOL_CALLS.md.hbs +35 -0
- package/assets/agents/_v2/coding/SYSTEM.md.hbs +173 -0
- package/assets/agents/_v2/explore.md.hbs +38 -0
- package/assets/agents/_v2/tui/SYSTEM.md.hbs +211 -0
- package/assets/agents/_v2/verifier.md.hbs +32 -0
- package/assets/agents/_v2/work/SYSTEM.md.hbs +186 -0
- package/assets/agents/_v2/worker.md.hbs +27 -0
- package/assets/agents/alran/PERSONA.md +7 -0
- package/assets/agents/alran/features/cron.md.hbs +0 -0
- package/assets/agents/alran/features/delegation.md.hbs +56 -0
- package/assets/agents/alran/features/memory.md.hbs +61 -0
- package/assets/agents/alran/features/recoverable-deletion.md.hbs +10 -0
- package/assets/agents/alran/features/task-management.md.hbs +11 -0
- package/assets/agents/alran/features/web-search.md.hbs +11 -0
- package/assets/agents/alran/modes/coding/online/PERSONA.md.hbs +20 -0
- package/assets/agents/alran/modes/coding/online/SYSTEM.md.hbs +158 -0
- package/assets/agents/alran/modes/work/online/PERSONA.md.hbs +20 -0
- package/assets/agents/alran/modes/work/online/SYSTEM.md.hbs +160 -0
- package/assets/agents/alran/prompt-session-root.md +4 -0
- package/assets/agents/alran/prompt-session-root.md.hbs +4 -0
- package/assets/agents/alran/skills/alran-code-product/SKILL.md +72 -0
- package/assets/agents/alran/skills/alran-code-product/references/account-models.md +61 -0
- package/assets/agents/alran/skills/alran-code-product/references/agents.md +34 -0
- package/assets/agents/alran/skills/alran-code-product/references/extensions.md +46 -0
- package/assets/agents/alran/skills/alran-code-product/references/workflows.md +56 -0
- package/assets/agents/alran/skills/control-in-app-browser/SKILL.md +590 -0
- package/assets/agents/alran/system-prompt.md.hbs +97 -0
- package/assets/agents/builtin-agents.json +1 -0
- package/assets/agents/desktop-task/archive-title/system-en.md +1 -0
- package/assets/agents/desktop-task/checkpoint/system.md +19 -0
- package/assets/agents/desktop-task/output-revision/system.md +1 -0
- package/assets/agents/desktop-task/retry/continuation.md +4 -0
- package/assets/agents/desktop-task/session-title/system.md +41 -0
- package/assets/agents/explore/PERSONA.md +8 -0
- package/assets/agents/explore/agent.md +14 -0
- package/assets/agents/explore/system-prompt.md.hbs +35 -0
- package/assets/agents/greeting.md +61 -0
- package/assets/agents/managed-prompts.json +47 -0
- package/assets/agents/prompt-exemptions.json +36 -0
- package/assets/agents/verifier/PERSONA.md +8 -0
- package/assets/agents/verifier/agent.md +17 -0
- package/assets/agents/verifier/system-prompt.md.hbs +28 -0
- package/assets/agents/worker/PERSONA.md +8 -0
- package/assets/agents/worker/agent.md +18 -0
- package/assets/agents/worker/system-prompt.md.hbs +22 -0
- package/assets/agents/workflow/code-review/review-candidates.md +120 -0
- package/assets/agents/workflow/code-review/reviewer-system.md +75 -0
- package/assets/agents/workflow/goal/budget-limit.md +16 -0
- package/assets/agents/workflow/goal/continuation.md +62 -0
- package/assets/agents/workflow/goal/objective-updated.md +16 -0
- package/assets/agents/workflow/goal/recovery-terminal-audit.md +13 -0
- package/assets/agents/workflow/goal/recovery.md +11 -0
- package/assets/agents/workflow/goal/terminal-audit.md +10 -0
- package/assets/agents/workflow/plan-mode/agent-entry.md +72 -0
- package/assets/agents/workflow/prompt-hook/system.md +0 -0
- package/assets/models-dev-catalog.json.gz +0 -0
- package/assets/prompts/code-review/review-candidates.md +120 -0
- package/assets/prompts/code-review/reviewer-system.md +75 -0
- package/assets/skills/alran-tools-master/SKILL.md +127 -0
- package/assets/skills/code-review/SKILL.md +51 -0
- package/assets/skills/cu-desktop/SKILL.md +255 -0
- package/assets/skills/deep-research/SKILL.md +30 -0
- package/assets/skills/deploy-website/SKILL.md +52 -0
- package/assets/skills/docx/LICENSE +21 -0
- package/assets/skills/docx/SKILL.md +259 -0
- package/assets/skills/docx/assets/styles/academic_styles.xml +250 -0
- package/assets/skills/docx/assets/styles/corporate_styles.xml +284 -0
- package/assets/skills/docx/assets/styles/default_styles.xml +449 -0
- package/assets/skills/docx/assets/xsd/aesthetic-rules.xsd +470 -0
- package/assets/skills/docx/assets/xsd/business-rules.xsd +130 -0
- package/assets/skills/docx/assets/xsd/common-types.xsd +159 -0
- package/assets/skills/docx/assets/xsd/wml-subset.xsd +589 -0
- package/assets/skills/docx/docs/acceptance-checklists/create.md +7 -0
- package/assets/skills/docx/docs/acceptance-checklists/edit.md +6 -0
- package/assets/skills/docx/docs/acceptance-checklists/layout-repair.md +7 -0
- package/assets/skills/docx/docs/acceptance-checklists/template.md +6 -0
- package/assets/skills/docx/docs/acceptance.md +139 -0
- package/assets/skills/docx/docs/anti-patterns.md +14 -0
- package/assets/skills/docx/docs/backends.md +116 -0
- package/assets/skills/docx/docs/evidence.md +73 -0
- package/assets/skills/docx/docs/failure-taxonomy.md +71 -0
- package/assets/skills/docx/docs/index.md +50 -0
- package/assets/skills/docx/docs/rendered-delivery.md +125 -0
- package/assets/skills/docx/docs/router.md +122 -0
- package/assets/skills/docx/docs/tables-and-numbering.md +27 -0
- package/assets/skills/docx/docs/task-apply-template.md +141 -0
- package/assets/skills/docx/docs/task-compare-two-docx.md +48 -0
- package/assets/skills/docx/docs/task-create.md +124 -0
- package/assets/skills/docx/docs/task-edit-fill.md +69 -0
- package/assets/skills/docx/docs/task-read-content.md +148 -0
- package/assets/skills/docx/docs/task-read-rendered.md +78 -0
- package/assets/skills/docx/docs/task-read-structure.md +93 -0
- package/assets/skills/docx/docs/task-repair-layout.md +70 -0
- package/assets/skills/docx/docs/template-dsl.md +32 -0
- package/assets/skills/docx/docs/track-changes.md +15 -0
- package/assets/skills/docx/docs/xml-patch-dsl.md +33 -0
- package/assets/skills/docx/references/cjk_typography.md +357 -0
- package/assets/skills/docx/references/cjk_university_template_guide.md +184 -0
- package/assets/skills/docx/references/comments_guide.md +191 -0
- package/assets/skills/docx/references/design_good_bad_examples.md +829 -0
- package/assets/skills/docx/references/design_principles.md +819 -0
- package/assets/skills/docx/references/openxml_element_order.md +308 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part1.md +4061 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part2.md +2820 -0
- package/assets/skills/docx/references/openxml_encyclopedia_part3.md +3381 -0
- package/assets/skills/docx/references/openxml_namespaces.md +82 -0
- package/assets/skills/docx/references/openxml_units.md +72 -0
- package/assets/skills/docx/references/sample-patch-plans.json +22 -0
- package/assets/skills/docx/references/sample-task-intents.json +5 -0
- package/assets/skills/docx/references/sample-template-manifests.json +21 -0
- package/assets/skills/docx/references/scenario_a_create.md +284 -0
- package/assets/skills/docx/references/scenario_b_edit_content.md +295 -0
- package/assets/skills/docx/references/scenario_c_apply_template.md +456 -0
- package/assets/skills/docx/references/track_changes_guide.md +200 -0
- package/assets/skills/docx/references/troubleshooting.md +506 -0
- package/assets/skills/docx/references/typography_guide.md +294 -0
- package/assets/skills/docx/references/xsd_validation_guide.md +158 -0
- package/assets/skills/docx/scripts/build_patch_plan.py +29 -0
- package/assets/skills/docx/scripts/diff_docx_structure.py +61 -0
- package/assets/skills/docx/scripts/doc_to_docx.ps1 +85 -0
- package/assets/skills/docx/scripts/doc_to_docx.sh +40 -0
- package/assets/skills/docx/scripts/docx_preview.ps1 +76 -0
- package/assets/skills/docx/scripts/docx_preview.sh +37 -0
- package/assets/skills/docx/scripts/docx_to_pdf.py +87 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/AlranAIDocx.Cli.csproj +19 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/Program.cs +18 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/AlranAIDocx.Core.csproj +15 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/AnalyzeCommand.cs +147 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ApplyTemplateCommand.cs +322 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/CreateCommand.cs +324 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/DiffCommand.cs +155 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/EditContentCommand.cs +487 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/FixOrderCommand.cs +108 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/MergeRunsCommand.cs +122 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ValidateCommand.cs +107 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/CommentSynchronizer.cs +169 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/ElementOrder.cs +80 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/NamespaceConstants.cs +42 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/RunMerger.cs +81 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/StyleAnalyzer.cs +81 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/TrackChangesHelper.cs +99 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/UnitConverter.cs +23 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples.cs +1832 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs +910 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs +999 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs +1048 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs +1038 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/CharacterFormattingSamples.cs +1020 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/DocumentCreationSamples.cs +1121 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FieldAndTocSamples.cs +624 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FootnoteAndCommentSamples.cs +675 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/HeaderFooterSamples.cs +838 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ImageSamples.cs +917 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ListAndNumberingSamples.cs +826 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ParagraphFormattingSamples.cs +1199 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/StyleSystemSamples.cs +1487 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TableSamples.cs +1163 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TrackChangesSamples.cs +595 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/CjkHelper.cs +39 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/FontDefaults.cs +24 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/PageSizes.cs +20 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/BusinessRuleValidator.cs +224 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/GateCheckValidator.cs +148 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/ValidationResult.cs +23 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/XsdValidator.cs +69 -0
- package/assets/skills/docx/scripts/dotnet/AlranAIDocx.slnx +4 -0
- package/assets/skills/docx/scripts/env_check.ps1 +327 -0
- package/assets/skills/docx/scripts/env_check.sh +340 -0
- package/assets/skills/docx/scripts/extract_docx_text.py +1075 -0
- package/assets/skills/docx/scripts/pack_docx.py +31 -0
- package/assets/skills/docx/scripts/read_docx_structure.py +1032 -0
- package/assets/skills/docx/scripts/render_docx_pages.py +147 -0
- package/assets/skills/docx/scripts/rendered_report.py +609 -0
- package/assets/skills/docx/scripts/setup.ps1 +542 -0
- package/assets/skills/docx/scripts/setup.sh +537 -0
- package/assets/skills/docx/scripts/unpack_docx.py +29 -0
- package/assets/skills/docx/scripts/validate_template_manifest.py +60 -0
- package/assets/skills/docx/scripts/verify_anchor_atomicity.py +87 -0
- package/assets/skills/edit-deployed-website/SKILL.md +27 -0
- package/assets/skills/init/SKILL.md +135 -0
- package/assets/skills/llm-call/SKILL.md +48 -0
- package/assets/skills/llm-call/scripts/llm_call.py +458 -0
- package/assets/skills/pdf/SKILL.md +280 -0
- package/assets/skills/pdf/docs/advanced-reference.md +711 -0
- package/assets/skills/pdf/docs/create-guide.md +437 -0
- package/assets/skills/pdf/docs/design-guide.md +204 -0
- package/assets/skills/pdf/docs/forms-guide.md +462 -0
- package/assets/skills/pdf/docs/html-pdf-spec.md +500 -0
- package/assets/skills/pdf/docs/latex-academic-thesis-guide.md +233 -0
- package/assets/skills/pdf/docs/latex-technical-book-guide.md +112 -0
- package/assets/skills/pdf/docs/pitfalls-index.md +792 -0
- package/assets/skills/pdf/docs/read-guide.md +358 -0
- package/assets/skills/pdf/docs/reformat-guide.md +238 -0
- package/assets/skills/pdf/docs/skill-readme-archive.md +151 -0
- package/assets/skills/pdf/docs/troubleshooting.md +86 -0
- package/assets/skills/pdf/docs/vision-guide.md +188 -0
- package/assets/skills/pdf/scripts/__init__.py +0 -0
- package/assets/skills/pdf/scripts/_pdf_read_lib.py +284 -0
- package/assets/skills/pdf/scripts/fill/__init__.py +0 -0
- package/assets/skills/pdf/scripts/fill/acroform_apply.py +153 -0
- package/assets/skills/pdf/scripts/fill/overlay_apply.py +109 -0
- package/assets/skills/pdf/scripts/lib/__init__.py +0 -0
- package/assets/skills/pdf/scripts/lib/acroform_io.py +170 -0
- package/assets/skills/pdf/scripts/lib/cli_utils.py +41 -0
- package/assets/skills/pdf/scripts/lib/geometry.py +79 -0
- package/assets/skills/pdf/scripts/make.sh +388 -0
- package/assets/skills/pdf/scripts/merge.py +112 -0
- package/assets/skills/pdf/scripts/pdf_inspect/__init__.py +0 -0
- package/assets/skills/pdf/scripts/pdf_inspect/acroform_inspect.py +52 -0
- package/assets/skills/pdf/scripts/pdf_inspect/acroform_probe.py +57 -0
- package/assets/skills/pdf/scripts/pdf_inspect/layout_scan.py +164 -0
- package/assets/skills/pdf/scripts/read_pdf_vision.py +473 -0
- package/assets/skills/pdf/scripts/reformat_parse.py +181 -0
- package/assets/skills/pdf/scripts/render/__init__.py +0 -0
- package/assets/skills/pdf/scripts/render/overlay_preview.py +86 -0
- package/assets/skills/pdf/scripts/render/page_rasterize.py +85 -0
- package/assets/skills/pdf/scripts/render_html.cjs +205 -0
- package/assets/skills/pdf/scripts/validate/__init__.py +0 -0
- package/assets/skills/pdf/scripts/validate/geometry_lint.py +124 -0
- package/assets/skills/pdf/templates/INDEX.md +90 -0
- package/assets/skills/pdf/templates/bilingual-menu-premium/README.md +175 -0
- package/assets/skills/pdf/templates/bilingual-menu-premium/skeleton.html +343 -0
- package/assets/skills/pdf/templates/brand-guide-2page/README.md +140 -0
- package/assets/skills/pdf/templates/brand-guide-2page/skeleton.html +264 -0
- package/assets/skills/pdf/templates/data-viz-report/README.md +234 -0
- package/assets/skills/pdf/templates/data-viz-report/skeleton.html +835 -0
- package/assets/skills/pdf/templates/form-fill-acroform/README.md +195 -0
- package/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json +118 -0
- package/assets/skills/pdf/templates/latex-academic-thesis/README.md +146 -0
- package/assets/skills/pdf/templates/latex-academic-thesis/source.tex +334 -0
- package/assets/skills/pdf/templates/latex-technical-book/README.md +130 -0
- package/assets/skills/pdf/templates/latex-technical-book/README.template-source.md +62 -0
- package/assets/skills/pdf/templates/latex-technical-book/source.tex +439 -0
- package/assets/skills/pdf/templates/multi-article-aggregator/README.md +148 -0
- package/assets/skills/pdf/templates/multi-article-aggregator/pipeline.md +223 -0
- package/assets/skills/pdf/templates/multilang-research-report/README.md +136 -0
- package/assets/skills/pdf/templates/multilang-research-report/skeleton.html +242 -0
- package/assets/skills/pdf/templates/reformat-default/README.md +136 -0
- package/assets/skills/pdf/templates/reformat-default/skeleton.html +204 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/README.md +136 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/skeleton.html +96 -0
- package/assets/skills/pdf/templates/translate-preserve-layout/terminology.template.json +66 -0
- package/assets/skills/pptx/SKILL.md +283 -0
- package/assets/skills/pptx/references/design-system.md +424 -0
- package/assets/skills/pptx/references/editing.md +162 -0
- package/assets/skills/pptx/references/element-map.md +229 -0
- package/assets/skills/pptx/references/pitfalls.md +205 -0
- package/assets/skills/pptx/references/pptxgenjs.md +420 -0
- package/assets/skills/pptx/references/preview-selection-writeback.md +65 -0
- package/assets/skills/pptx/references/python-pptx-recipes.md +63 -0
- package/assets/skills/pptx/references/slide-types.md +413 -0
- package/assets/skills/pptx/scripts/alran-ppt-map.cjs +280 -0
- package/assets/skills/pptx/scripts/audit_pptx.py +708 -0
- package/assets/skills/pptx/scripts/extract_comments.py +468 -0
- package/assets/skills/pptx/scripts/extract_images.py +226 -0
- package/assets/skills/pptx/scripts/extract_pptx.py +285 -0
- package/assets/skills/pptx/scripts/pdf2png.swift +203 -0
- package/assets/skills/pptx/scripts/pptx-screenshot.sh +105 -0
- package/assets/skills/resume-codex/SKILL.md +53 -0
- package/assets/skills/resume-codex/scripts/session-reader.mjs +445 -0
- package/assets/skills/skill-creator/SKILL.md +188 -0
- package/assets/skills/skill-creator/references/anti-patterns.md +149 -0
- package/assets/skills/skill-creator/references/commands-macos-linux.md +38 -0
- package/assets/skills/skill-creator/references/commands-windows-powershell.md +48 -0
- package/assets/skills/skill-creator/references/description-rubric.md +83 -0
- package/assets/skills/skill-creator/references/skill-template.md +101 -0
- package/assets/skills/skill-creator/references/when-to-bundle-scripts.md +139 -0
- package/assets/skills/skill-creator/scripts/lint-skill.js +226 -0
- package/assets/skills/skill-refiner/SKILL.md +137 -0
- package/assets/skills/visual-page/SKILL.md +194 -0
- package/assets/skills/x-link-reader/SKILL.md +108 -0
- package/assets/skills/xlsx/SKILL.md +498 -0
- package/assets/skills/xlsx/docs/advanced-reference.md +410 -0
- package/assets/skills/xlsx/docs/conventions-guide.md +217 -0
- package/assets/skills/xlsx/docs/create-edit-guide.md +410 -0
- package/assets/skills/xlsx/docs/pitfalls-index.md +759 -0
- package/assets/skills/xlsx/docs/raw-xml-escape-hatch.md +201 -0
- package/assets/skills/xlsx/docs/recalc-guide.md +295 -0
- package/assets/skills/xlsx/scripts/office/helpers/__init__.py +0 -0
- package/assets/skills/xlsx/scripts/office/helpers/merge_runs.py +199 -0
- package/assets/skills/xlsx/scripts/office/helpers/simplify_redlines.py +197 -0
- package/assets/skills/xlsx/scripts/office/pack.py +159 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
- package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
- package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
- package/assets/skills/xlsx/scripts/office/schemas/mce/mc.xsd +75 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd +560 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd +67 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd +14 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd +20 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd +13 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
- package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd +8 -0
- package/assets/skills/xlsx/scripts/office/soffice.py +191 -0
- package/assets/skills/xlsx/scripts/office/unpack.py +132 -0
- package/assets/skills/xlsx/scripts/office/validate.py +117 -0
- package/assets/skills/xlsx/scripts/office/validators/__init__.py +15 -0
- package/assets/skills/xlsx/scripts/office/validators/base.py +851 -0
- package/assets/skills/xlsx/scripts/office/validators/docx.py +446 -0
- package/assets/skills/xlsx/scripts/office/validators/pptx.py +275 -0
- package/assets/skills/xlsx/scripts/office/validators/redlining.py +247 -0
- package/assets/skills/xlsx/scripts/recalc.py +450 -0
- package/chunks/account-commands-JZ6NXTTK.js +2 -0
- package/chunks/anthropic-MN33DP4E.js +2 -0
- package/chunks/application-ITGAJ4HC.js +2 -0
- package/chunks/auth-command-V3RVPLZO.js +2 -0
- package/chunks/azure-openai-responses-OWHMUNKC.js +2 -0
- package/chunks/chunk-2TF6JAQM.js +2 -0
- package/chunks/chunk-33CNY6GP.js +2 -0
- package/chunks/chunk-3AODGLMF.js +2 -0
- package/chunks/chunk-44VPC5LA.js +38 -0
- package/chunks/chunk-4CN3IJFH.js +2 -0
- package/chunks/chunk-4PDIO3M6.js +2 -0
- package/chunks/chunk-4X22UJQH.js +164 -0
- package/chunks/chunk-6255CZPL.js +2 -0
- package/chunks/chunk-6P4UKHGR.js +2 -0
- package/chunks/chunk-7QLAXRD2.js +1085 -0
- package/chunks/chunk-7XYOYZX2.js +2 -0
- package/chunks/chunk-A7GMJNA2.js +29 -0
- package/chunks/chunk-AGUSPIUP.js +2 -0
- package/chunks/chunk-BQ3CF3KE.js +2 -0
- package/chunks/chunk-C3CMJAAV.js +3 -0
- package/chunks/chunk-CJM7ZJ6W.js +7 -0
- package/chunks/chunk-CSOUJVKM.js +2 -0
- package/chunks/chunk-D66ZSHXR.js +2 -0
- package/chunks/chunk-D7MGU75P.js +2 -0
- package/chunks/chunk-E3GLGDGC.js +5 -0
- package/chunks/chunk-ENHOPPS7.js +16 -0
- package/chunks/chunk-EOR6EDNR.js +2 -0
- package/chunks/chunk-EYK25HWR.js +2 -0
- package/chunks/chunk-F46IELF5.js +2 -0
- package/chunks/chunk-FC4M2B7E.js +2 -0
- package/chunks/chunk-FSNYOJPJ.js +2 -0
- package/chunks/chunk-FUERW2DW.js +3 -0
- package/chunks/chunk-FXOH6TEQ.js +21 -0
- package/chunks/chunk-GP52JZMY.js +2 -0
- package/chunks/chunk-GRXX6I72.js +2 -0
- package/chunks/chunk-GSYHBK5Q.js +6 -0
- package/chunks/chunk-HNWBFJNO.js +2 -0
- package/chunks/chunk-IIE366LR.js +6706 -0
- package/chunks/chunk-IWK7PZP7.js +207 -0
- package/chunks/chunk-J3KCPYZT.js +2 -0
- package/chunks/chunk-KCLRJQ53.js +59 -0
- package/chunks/chunk-LU4RPLJ3.js +2 -0
- package/chunks/chunk-LZJYNT32.js +2 -0
- package/chunks/chunk-M7GW4VMR.js +27 -0
- package/chunks/chunk-MACBL5HF.js +2 -0
- package/chunks/chunk-N5NTXCJI.js +2 -0
- package/chunks/chunk-N5SVBCUB.js +7 -0
- package/chunks/chunk-N6W7ZL26.js +2 -0
- package/chunks/chunk-NWB7LFOK.js +131 -0
- package/chunks/chunk-OIQ336YE.js +16 -0
- package/chunks/chunk-OQNU3VPS.js +30 -0
- package/chunks/chunk-OTDNOWXG.js +16 -0
- package/chunks/chunk-PNXZWSWT.js +3 -0
- package/chunks/chunk-QFUV5PX6.js +2 -0
- package/chunks/chunk-QIN5ZBE2.js +2 -0
- package/chunks/chunk-QKBN5CGI.js +2 -0
- package/chunks/chunk-QPGTKSIQ.js +2 -0
- package/chunks/chunk-SIOLUFGG.js +2 -0
- package/chunks/chunk-TW23QKAD.js +3 -0
- package/chunks/chunk-U3RMPDXU.js +2 -0
- package/chunks/chunk-U7U3DJHF.js +2 -0
- package/chunks/chunk-VLXX22YO.js +2 -0
- package/chunks/chunk-WHD2XVT2.js +2 -0
- package/chunks/chunk-WTAJMYF2.js +249 -0
- package/chunks/chunk-WWNUAU4P.js +29 -0
- package/chunks/chunk-WYANV3IX.js +4 -0
- package/chunks/chunk-XAGZ6ZEU.js +9 -0
- package/chunks/chunk-XFCC2CI2.js +24 -0
- package/chunks/chunk-XQK7JM66.js +2 -0
- package/chunks/chunk-YLQXZBEL.js +2 -0
- package/chunks/chunk-YPV2X2RG.js +2 -0
- package/chunks/chunk-Z6BHCXKT.js +25 -0
- package/chunks/chunk-Z6HBNJCA.js +8 -0
- package/chunks/chunk-ZQKVUPKA.js +2 -0
- package/chunks/chunk-ZQOALVGL.js +2 -0
- package/chunks/clipboard-image-PQPC4EHR.js +2 -0
- package/chunks/data-dir-LDVKDCJ2.js +2 -0
- package/chunks/dist-2BRD4JFU.js +11 -0
- package/chunks/dist-EXKHRFQO.js +5 -0
- package/chunks/emscripten-module-RD6P2XH5.js +2 -0
- package/chunks/emscripten-module-WYNDFH3N.js +2 -0
- package/chunks/emscripten-module-XPTEOIWW.js +2 -0
- package/chunks/emscripten-module-ZS3PMSDF.js +2 -0
- package/chunks/ffi-IO7WZQNG.js +2 -0
- package/chunks/ffi-M5UP5J6C.js +2 -0
- package/chunks/ffi-ORLOPBB3.js +2 -0
- package/chunks/ffi-OUPK6AY6.js +2 -0
- package/chunks/google-UJAPMFAB.js +2 -0
- package/chunks/google-vertex-VLSF55PW.js +2 -0
- package/chunks/install-source-JTIUC4G4.js +2 -0
- package/chunks/launcher-FCZ3EDBF.js +61 -0
- package/chunks/lifecycle-GY435YMF.js +2 -0
- package/chunks/main-TQGGRHTS.js +13 -0
- package/chunks/mistral-ZJZUEF2X.js +3 -0
- package/chunks/module-6F3E5H7Y-BN7QWGYB.js +2 -0
- package/chunks/module-asyncify-R6PWJ6ZV-P4FWSBAY.js +2 -0
- package/chunks/multipart-parser-L6M455MS.js +2 -0
- package/chunks/network-proxy-U72JCK2I.js +2 -0
- package/chunks/openai-codex-responses-FPCDNRL5.js +2 -0
- package/chunks/openai-completions-D32YW6KL.js +2 -0
- package/chunks/openai-responses-ZCGSENM4.js +2 -0
- package/chunks/openrouter-G2EHY5BD.js +2 -0
- package/chunks/otel-OHXIZ666.js +2 -0
- package/chunks/package-contract-GVXTMJ3N.js +2 -0
- package/chunks/pdfjs-SHZAF7PF.js +107 -0
- package/chunks/photon_rs-C52RL4CI.js +3 -0
- package/chunks/plugin-command-OSAFHS7C.js +2 -0
- package/chunks/provider-command-SKTCHD4E.js +2 -0
- package/chunks/questionnaire-bridge-ISQOCYWY.js +2 -0
- package/chunks/run-acp-command-SG2BDMFJ.js +2 -0
- package/chunks/run-exec-command-5ADSQR2Z.js +15 -0
- package/chunks/skills-command-XXXEZAG6.js +2 -0
- package/chunks/src-DNIDEMVV.js +2 -0
- package/chunks/src-IBHIRTD7.js +2 -0
- package/chunks/telemetry-J7ZLGF5X.js +2 -0
- package/chunks/telemetry-command-COQG2AKK.js +5 -0
- package/chunks/tools-WDBB2JKV.js +2 -0
- package/chunks/undici-TUGHZJSA.js +2 -0
- package/chunks/update-NB6OD572.js +14 -0
- package/chunks/update-hint-ED7O67WU.js +3 -0
- package/chunks/wechat-onboard-UWXQW2HT.js +2 -0
- package/cli.js +5 -0
- package/configs/data-minimal.yaml +50 -0
- package/embedded/alran-tools/cli.mjs +4961 -0
- package/embedded/alran-tools/manifest.json +25 -0
- package/emscripten-module.wasm +0 -0
- package/image-preview-worker.js +2 -0
- package/internal-bin/alran-tools +9 -0
- package/internal-bin/alran-tools.cmd +8 -0
- package/matrix-mcp-stdio.js +4 -0
- package/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node +0 -0
- package/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node +0 -0
- package/native/win32/prebuilds/win32-arm64/win32-console-mode.node +0 -0
- package/native/win32/prebuilds/win32-x64/win32-console-mode.node +0 -0
- package/package.json +38 -4
- package/photon_rs_bg.wasm +0 -0
- package/quickjs-worker.js +152 -0
- package/vendor/java-proxy-agent/build.ts +97 -0
- package/vendor/java-proxy-agent/srt-proxy-agent.jar +0 -0
- package/vendor/seccomp/arm64/apply-seccomp +0 -0
- package/vendor/seccomp/build.ts +74 -0
- package/vendor/seccomp/x64/apply-seccomp +0 -0
- package/vendor/srt-win/arm64/srt-win.exe +0 -0
- package/vendor/srt-win/build.ts +40 -0
- package/vendor/srt-win/x64/srt-win.exe +0 -0
|
@@ -0,0 +1,711 @@
|
|
|
1
|
+
# Advanced Reference
|
|
2
|
+
|
|
3
|
+
Maintained by Alran (MIT). This reference collects PDF features and
|
|
4
|
+
libraries that are too situational for the main `SKILL.md`. Reach for
|
|
5
|
+
it when the standard recipes in `create-guide.md` / `forms-guide.md` /
|
|
6
|
+
`read-guide.md` are not enough.
|
|
7
|
+
|
|
8
|
+
All in-tree script invocations live under `scripts/` and are dispatched
|
|
9
|
+
through `bash scripts/make.sh ...`. The fill / pdf_inspect / render / validate
|
|
10
|
+
subpackages can also be run directly as `python -m scripts.<group>.<name>`
|
|
11
|
+
from the skill root when you need fine-grained control.
|
|
12
|
+
|
|
13
|
+
Global navigation rule for every mutation path: when you merge, split, rotate,
|
|
14
|
+
crop, watermark, encrypt, annotate, sign, or otherwise rebuild a PDF, preserve
|
|
15
|
+
existing TOC links, named destinations, outlines/bookmarks, and `/Link`
|
|
16
|
+
annotations whenever possible. If page order or page offsets change, update the
|
|
17
|
+
visible TOC/index, outlines, and link destinations so they still land on the
|
|
18
|
+
correct pages. For any newly assembled multi-page output, add clickable
|
|
19
|
+
TOC/index navigation before delivery; do not ship a merged packet whose first
|
|
20
|
+
page is an inert list of page numbers.
|
|
21
|
+
|
|
22
|
+
> **Note on the `pdf_inspect/` directory name.** It is deliberately
|
|
23
|
+
> *not* called `inspect/`. Python ≥ 3.11 colourised tracebacks pull
|
|
24
|
+
> ``inspect.signature`` in via ``argparse → _colorize → dataclasses``, and
|
|
25
|
+
> any package named ``inspect`` placed first on ``sys.path`` (which the
|
|
26
|
+
> CPython "script directory at index 0" rule does for entry-point
|
|
27
|
+
> scripts) shadows the stdlib module and breaks every renderer that
|
|
28
|
+
> transitively touches it (reportlab → PIL → typing_extensions). The
|
|
29
|
+
> rename is structural insulation against that whole class of bugs.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 1. pypdfium2 — High-Performance Rendering
|
|
34
|
+
|
|
35
|
+
`pypdfium2` is the Python binding for PDFium (Chromium's PDF engine).
|
|
36
|
+
It is the fastest mainstream renderer in the Python ecosystem.
|
|
37
|
+
|
|
38
|
+
### 1.1 Render a page to PIL
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import pypdfium2 as pdfium
|
|
42
|
+
src_doc = pdfium.PdfDocument("invoice.pdf")
|
|
43
|
+
pg = src_doc[0]
|
|
44
|
+
bitmap = pg.render(scale=2.0, rotation=0)
|
|
45
|
+
bitmap.to_pil().save("invoice_page_1.png", "PNG")
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### 1.2 Render every page to JPEG
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
import pypdfium2 as pdfium
|
|
52
|
+
src_doc = pdfium.PdfDocument("payslip.pdf")
|
|
53
|
+
for i, pg in enumerate(src_doc):
|
|
54
|
+
pg.render(scale=1.5).to_pil().save(f"payslip_{i + 1}.jpg", "JPEG", quality=90)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### 1.3 Cheap text extraction
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
import pypdfium2 as pdfium
|
|
61
|
+
src_doc = pdfium.PdfDocument("payslip.pdf")
|
|
62
|
+
for i, pg in enumerate(src_doc):
|
|
63
|
+
body = pg.get_text()
|
|
64
|
+
print(f"page {i + 1}: {len(body)} chars")
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 2. JavaScript Libraries
|
|
70
|
+
|
|
71
|
+
These are useful when the surrounding application is a Node service or
|
|
72
|
+
a browser front-end. They are listed here only for completeness; the
|
|
73
|
+
in-tree scripts are pure Python.
|
|
74
|
+
|
|
75
|
+
### 2.1 pdf-lib (MIT)
|
|
76
|
+
|
|
77
|
+
`pdf-lib` works in any JavaScript runtime — Node, Deno, browsers — and
|
|
78
|
+
preserves form structure better than most alternatives.
|
|
79
|
+
|
|
80
|
+
#### Manipulate an existing document
|
|
81
|
+
|
|
82
|
+
```javascript
|
|
83
|
+
import { PDFDocument } from 'pdf-lib';
|
|
84
|
+
import fs from 'fs';
|
|
85
|
+
|
|
86
|
+
async function tweak() {
|
|
87
|
+
const bytes = fs.readFileSync('invoice.pdf');
|
|
88
|
+
const doc = await PDFDocument.load(bytes);
|
|
89
|
+
|
|
90
|
+
console.log(`pages: ${doc.getPageCount()}`);
|
|
91
|
+
const pg = doc.addPage([600, 400]);
|
|
92
|
+
pg.drawText('Added by pdf-lib', { x: 100, y: 300, size: 16 });
|
|
93
|
+
|
|
94
|
+
fs.writeFileSync('invoice-modified.pdf', await doc.save());
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
#### Author from scratch
|
|
99
|
+
|
|
100
|
+
```javascript
|
|
101
|
+
import { PDFDocument, rgb, StandardFonts } from 'pdf-lib';
|
|
102
|
+
import fs from 'fs';
|
|
103
|
+
|
|
104
|
+
async function makeInvoice() {
|
|
105
|
+
const doc = await PDFDocument.create();
|
|
106
|
+
const bold = await doc.embedFont(StandardFonts.HelveticaBold);
|
|
107
|
+
const pg = doc.addPage([595, 842]);
|
|
108
|
+
const { width, height } = pg.getSize();
|
|
109
|
+
|
|
110
|
+
pg.drawText('Invoice 2026-04-21', {
|
|
111
|
+
x: 50, y: height - 50, size: 18, font: bold, color: rgb(0.2, 0.2, 0.8),
|
|
112
|
+
});
|
|
113
|
+
pg.drawRectangle({
|
|
114
|
+
x: 40, y: height - 100, width: width - 80, height: 30,
|
|
115
|
+
color: rgb(0.9, 0.9, 0.9),
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
fs.writeFileSync('invoice-new.pdf', await doc.save());
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
#### Merge selected pages
|
|
123
|
+
|
|
124
|
+
```javascript
|
|
125
|
+
import { PDFDocument } from 'pdf-lib';
|
|
126
|
+
import fs from 'fs';
|
|
127
|
+
|
|
128
|
+
async function combine() {
|
|
129
|
+
const merged = await PDFDocument.create();
|
|
130
|
+
|
|
131
|
+
const a = await PDFDocument.load(fs.readFileSync('a.pdf'));
|
|
132
|
+
const b = await PDFDocument.load(fs.readFileSync('b.pdf'));
|
|
133
|
+
|
|
134
|
+
(await merged.copyPages(a, a.getPageIndices()))
|
|
135
|
+
.forEach(pg => merged.addPage(pg));
|
|
136
|
+
(await merged.copyPages(b, [0, 2, 4]))
|
|
137
|
+
.forEach(pg => merged.addPage(pg));
|
|
138
|
+
|
|
139
|
+
fs.writeFileSync('combined.pdf', await merged.save());
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### 2.2 pdfjs-dist (Apache)
|
|
144
|
+
|
|
145
|
+
Mozilla's PDF.js, packaged for npm. Used primarily inside browsers.
|
|
146
|
+
|
|
147
|
+
```javascript
|
|
148
|
+
import * as pdfjsLib from 'pdfjs-dist';
|
|
149
|
+
pdfjsLib.GlobalWorkerOptions.workerSrc = './pdf.worker.js';
|
|
150
|
+
|
|
151
|
+
async function show() {
|
|
152
|
+
const pdf = await pdfjsLib.getDocument('invoice.pdf').promise;
|
|
153
|
+
const pg = await pdf.getPage(1);
|
|
154
|
+
const vp = pg.getViewport({ scale: 1.5 });
|
|
155
|
+
|
|
156
|
+
const cv = document.createElement('canvas');
|
|
157
|
+
cv.width = vp.width;
|
|
158
|
+
cv.height = vp.height;
|
|
159
|
+
await pg.render({ canvasContext: cv.getContext('2d'), viewport: vp }).promise;
|
|
160
|
+
document.body.appendChild(cv);
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Extract text with coordinates:
|
|
165
|
+
|
|
166
|
+
```javascript
|
|
167
|
+
async function harvest() {
|
|
168
|
+
const pdf = await pdfjsLib.getDocument('invoice.pdf').promise;
|
|
169
|
+
for (let i = 1; i <= pdf.numPages; i++) {
|
|
170
|
+
const pg = await pdf.getPage(i);
|
|
171
|
+
const txt = await pg.getTextContent();
|
|
172
|
+
const items = txt.items.map(it => ({
|
|
173
|
+
text: it.str,
|
|
174
|
+
x: it.transform[4],
|
|
175
|
+
y: it.transform[5],
|
|
176
|
+
w: it.width,
|
|
177
|
+
h: it.height,
|
|
178
|
+
}));
|
|
179
|
+
console.log(`page ${i} - ${items.length} runs`);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Pull form/annotation metadata:
|
|
185
|
+
|
|
186
|
+
```javascript
|
|
187
|
+
async function annotations() {
|
|
188
|
+
const pdf = await pdfjsLib.getDocument('annotated.pdf').promise;
|
|
189
|
+
for (let i = 1; i <= pdf.numPages; i++) {
|
|
190
|
+
const pg = await pdf.getPage(i);
|
|
191
|
+
for (const a of await pg.getAnnotations()) {
|
|
192
|
+
console.log(a.subtype, a.contents, a.rect);
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 3. Heavy CLI Recipes
|
|
201
|
+
|
|
202
|
+
### 3.1 poppler-utils (advanced)
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
# Text + bounding boxes (XML)
|
|
206
|
+
pdftotext -bbox-layout invoice.pdf invoice.xml
|
|
207
|
+
|
|
208
|
+
# Render with explicit DPI
|
|
209
|
+
pdftoppm -png -r 300 invoice.pdf out_prefix
|
|
210
|
+
|
|
211
|
+
# Range with high resolution
|
|
212
|
+
pdftoppm -png -r 600 -f 1 -l 3 invoice.pdf high_res
|
|
213
|
+
|
|
214
|
+
# JPEG with quality knob
|
|
215
|
+
pdftoppm -jpeg -jpegopt quality=85 -r 200 invoice.pdf jpeg_out
|
|
216
|
+
|
|
217
|
+
# Pull all images, with metadata
|
|
218
|
+
pdfimages -j -p invoice.pdf images/
|
|
219
|
+
|
|
220
|
+
# List images without extracting
|
|
221
|
+
pdfimages -list invoice.pdf
|
|
222
|
+
|
|
223
|
+
# Original-format extraction
|
|
224
|
+
pdfimages -all invoice.pdf images/img
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### 3.2 qpdf (advanced)
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
# Split into N-page chunks
|
|
231
|
+
qpdf --split-pages=3 invoice.pdf out_%02d.pdf
|
|
232
|
+
|
|
233
|
+
# Custom page picks
|
|
234
|
+
qpdf invoice.pdf --pages invoice.pdf 1,3-5,8,10-end -- subset.pdf
|
|
235
|
+
|
|
236
|
+
# Cross-document merge with per-source ranges
|
|
237
|
+
qpdf --empty --pages a.pdf 1-3 b.pdf 5-7 c.pdf 2,4 -- combined.pdf
|
|
238
|
+
|
|
239
|
+
# Linearise for streaming
|
|
240
|
+
qpdf --linearize invoice.pdf invoice-web.pdf
|
|
241
|
+
|
|
242
|
+
# Optimisation
|
|
243
|
+
qpdf --optimize-level=all invoice.pdf invoice-small.pdf
|
|
244
|
+
|
|
245
|
+
# Repair
|
|
246
|
+
qpdf --check broken.pdf
|
|
247
|
+
qpdf --fix-qdf damaged.pdf repaired.pdf
|
|
248
|
+
|
|
249
|
+
# Encryption with explicit permissions
|
|
250
|
+
qpdf --encrypt user_pw owner_pw 256 --print=none --modify=none -- in.pdf out.pdf
|
|
251
|
+
|
|
252
|
+
# Inspection
|
|
253
|
+
qpdf --show-encryption out.pdf
|
|
254
|
+
qpdf --password=pw --decrypt out.pdf clear.pdf
|
|
255
|
+
qpdf --show-all-pages invoice.pdf > structure.txt
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### 3.3 pdftk (fallback when qpdf is unavailable)
|
|
259
|
+
|
|
260
|
+
`pdftk` predates qpdf and survives on systems where qpdf is hard to install
|
|
261
|
+
(some old Linux distros, locked-down corporate machines). Recipes are coarser
|
|
262
|
+
than qpdf but the binary is widely packaged.
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
# Merge
|
|
266
|
+
pdftk a.pdf b.pdf cat output merged.pdf
|
|
267
|
+
|
|
268
|
+
# Split into one file per page
|
|
269
|
+
pdftk input.pdf burst # produces pg_0001.pdf, pg_0002.pdf, ...
|
|
270
|
+
|
|
271
|
+
# Rotate single pages (east = +90 clockwise, west = -90, south = 180)
|
|
272
|
+
pdftk input.pdf rotate 1east output rotated.pdf
|
|
273
|
+
|
|
274
|
+
# Concatenate selected page ranges across files
|
|
275
|
+
pdftk A=a.pdf B=b.pdf cat A1-3 B5-7 output combined.pdf
|
|
276
|
+
|
|
277
|
+
# Encrypt (AES-128)
|
|
278
|
+
pdftk input.pdf output secured.pdf owner_pw owner_pass user_pw user_pass
|
|
279
|
+
|
|
280
|
+
# Decrypt (requires owner password)
|
|
281
|
+
pdftk secured.pdf input_pw owner_pass output clear.pdf
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Prefer qpdf where both are installed: qpdf has finer optimisation knobs,
|
|
285
|
+
better repair, and AES-256 support; pdftk is the safety net.
|
|
286
|
+
|
|
287
|
+
---
|
|
288
|
+
|
|
289
|
+
## 4. Advanced Python
|
|
290
|
+
|
|
291
|
+
### 4.1 pdfplumber — coordinate-aware extraction
|
|
292
|
+
|
|
293
|
+
```python
|
|
294
|
+
import pdfplumber
|
|
295
|
+
with pdfplumber.open("payslip.pdf") as src_doc:
|
|
296
|
+
pg = src_doc.pages[0]
|
|
297
|
+
for ch in pg.chars[:10]:
|
|
298
|
+
print(ch["text"], ch["x0"], ch["top"])
|
|
299
|
+
region = pg.within_bbox((100, 100, 400, 200)).extract_text()
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Custom table strategy:
|
|
303
|
+
|
|
304
|
+
```python
|
|
305
|
+
import pdfplumber
|
|
306
|
+
import pandas as pd
|
|
307
|
+
|
|
308
|
+
with pdfplumber.open("complex_table.pdf") as src_doc:
|
|
309
|
+
pg = src_doc.pages[0]
|
|
310
|
+
settings = {
|
|
311
|
+
"vertical_strategy": "lines",
|
|
312
|
+
"horizontal_strategy": "lines",
|
|
313
|
+
"snap_tolerance": 3,
|
|
314
|
+
"intersection_tolerance": 15,
|
|
315
|
+
}
|
|
316
|
+
tbls = pg.extract_tables(settings)
|
|
317
|
+
pg.to_image(resolution=150).save("debug.png")
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
### 4.2 reportlab — styled tables
|
|
321
|
+
|
|
322
|
+
```python
|
|
323
|
+
from reportlab.platypus import (
|
|
324
|
+
SimpleDocTemplate, Table, TableStyle, Paragraph,
|
|
325
|
+
)
|
|
326
|
+
from reportlab.lib.styles import getSampleStyleSheet
|
|
327
|
+
from reportlab.lib import colors
|
|
328
|
+
|
|
329
|
+
rows = [
|
|
330
|
+
["Product", "Q1", "Q2", "Q3", "Q4"],
|
|
331
|
+
["Widgets", "120", "135", "142", "158"],
|
|
332
|
+
["Gadgets", "85", "92", "98", "105"],
|
|
333
|
+
]
|
|
334
|
+
|
|
335
|
+
doc = SimpleDocTemplate("sales.pdf")
|
|
336
|
+
story = [Paragraph("Quarterly Sales", getSampleStyleSheet()["Title"])]
|
|
337
|
+
tbl = Table(rows)
|
|
338
|
+
tbl.setStyle(TableStyle([
|
|
339
|
+
("BACKGROUND", (0, 0), (-1, 0), colors.grey),
|
|
340
|
+
("TEXTCOLOR", (0, 0), (-1, 0), colors.whitesmoke),
|
|
341
|
+
("ALIGN", (0, 0), (-1, -1), "CENTER"),
|
|
342
|
+
("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
|
|
343
|
+
("FONTSIZE", (0, 0), (-1, 0), 14),
|
|
344
|
+
("BOTTOMPADDING", (0, 0), (-1, 0), 12),
|
|
345
|
+
("BACKGROUND", (0, 1), (-1, -1), colors.beige),
|
|
346
|
+
("GRID", (0, 0), (-1, -1), 1, colors.black),
|
|
347
|
+
]))
|
|
348
|
+
story.append(tbl)
|
|
349
|
+
doc.build(story)
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
---
|
|
353
|
+
|
|
354
|
+
## 5. Annotations, Signatures, and Text Overlay
|
|
355
|
+
|
|
356
|
+
Three related mutation routes for annotating an existing PDF without
|
|
357
|
+
rebuilding the page. All keep the original content stream intact and
|
|
358
|
+
either add an annotation object or stack an overlay on top.
|
|
359
|
+
|
|
360
|
+
### 5.1 Sticky note annotations (`/Text` subtype)
|
|
361
|
+
|
|
362
|
+
Sticky notes show as a clickable icon in Adobe Acrobat / macOS Preview;
|
|
363
|
+
the comment text appears when the icon is opened.
|
|
364
|
+
|
|
365
|
+
```python
|
|
366
|
+
from pypdf import PdfReader, PdfWriter
|
|
367
|
+
from pypdf.generic import (
|
|
368
|
+
DictionaryObject, ArrayObject, FloatObject,
|
|
369
|
+
NameObject, TextStringObject, NumberObject, BooleanObject,
|
|
370
|
+
)
|
|
371
|
+
|
|
372
|
+
def make_sticky_note(x, y, w, h, *, subject, contents, color=(1, 1, 0)):
|
|
373
|
+
annot = DictionaryObject()
|
|
374
|
+
annot[NameObject("/Type")] = NameObject("/Annot")
|
|
375
|
+
annot[NameObject("/Subtype")] = NameObject("/Text")
|
|
376
|
+
annot[NameObject("/Rect")] = ArrayObject([
|
|
377
|
+
FloatObject(x), FloatObject(y),
|
|
378
|
+
FloatObject(x + w), FloatObject(y + h),
|
|
379
|
+
])
|
|
380
|
+
annot[NameObject("/T")] = TextStringObject("Reviewer")
|
|
381
|
+
annot[NameObject("/Subj")] = TextStringObject(subject)
|
|
382
|
+
annot[NameObject("/Contents")] = TextStringObject(contents)
|
|
383
|
+
annot[NameObject("/Open")] = BooleanObject(False)
|
|
384
|
+
annot[NameObject("/C")] = ArrayObject([FloatObject(c) for c in color])
|
|
385
|
+
annot[NameObject("/F")] = NumberObject(4) # Print flag
|
|
386
|
+
annot[NameObject("/Name")] = NameObject("/Note")
|
|
387
|
+
return annot
|
|
388
|
+
|
|
389
|
+
reader = PdfReader("input.pdf")
|
|
390
|
+
writer = PdfWriter()
|
|
391
|
+
for pg in reader.pages:
|
|
392
|
+
writer.add_page(pg)
|
|
393
|
+
|
|
394
|
+
page = writer.pages[0]
|
|
395
|
+
page_h = float(page.mediabox.height)
|
|
396
|
+
|
|
397
|
+
# pdfplumber `top` is from the page TOP; pypdf y is from the page BOTTOM:
|
|
398
|
+
# pypdf_y = page_h - pdfplumber_top
|
|
399
|
+
note = make_sticky_note(54, page_h - 270, 20, 20,
|
|
400
|
+
subject="Review", contents="Must order!")
|
|
401
|
+
note_ref = writer._add_object(note)
|
|
402
|
+
|
|
403
|
+
# Append to the existing /Annots, never overwrite:
|
|
404
|
+
existing = page.get("/Annots")
|
|
405
|
+
existing_list = list(existing) if existing else []
|
|
406
|
+
existing_list.append(note_ref)
|
|
407
|
+
page[NameObject("/Annots")] = ArrayObject(existing_list)
|
|
408
|
+
|
|
409
|
+
with open("output.pdf", "wb") as fp:
|
|
410
|
+
writer.write(fp)
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
Notes:
|
|
414
|
+
|
|
415
|
+
- `/F` = 4 sets the Print flag — without it some viewers omit the
|
|
416
|
+
annotation when printing.
|
|
417
|
+
- `/C` is a 0-1 RGB tuple, not 0-255.
|
|
418
|
+
- Chromium's built-in PDF viewer ignores annotations; verify with
|
|
419
|
+
Acrobat, Preview, or `pdftotext -annotate`.
|
|
420
|
+
|
|
421
|
+
### 5.2 Visible signatures and stamps (`/FreeText` subtype)
|
|
422
|
+
|
|
423
|
+
`FreeText` renders text directly on the page (no click-to-open icon) —
|
|
424
|
+
the standard way to add a visible signature, date stamp, or watermark
|
|
425
|
+
without rebuilding the page.
|
|
426
|
+
|
|
427
|
+
```python
|
|
428
|
+
sig = DictionaryObject()
|
|
429
|
+
sig[NameObject("/Type")] = NameObject("/Annot")
|
|
430
|
+
sig[NameObject("/Subtype")] = NameObject("/FreeText")
|
|
431
|
+
sig[NameObject("/Rect")] = ArrayObject([
|
|
432
|
+
FloatObject(x), FloatObject(y),
|
|
433
|
+
FloatObject(x + width), FloatObject(y + height),
|
|
434
|
+
])
|
|
435
|
+
sig[NameObject("/Contents")] = TextStringObject("J. Doe\n2026.04.21")
|
|
436
|
+
# /DA = "/FontName Size Tf R G B rg" (RGB are 0-1)
|
|
437
|
+
sig[NameObject("/DA")] = TextStringObject("/Helvetica 16 Tf 0.1 0.1 0.35 rg")
|
|
438
|
+
sig[NameObject("/F")] = NumberObject(4)
|
|
439
|
+
sig[NameObject("/C")] = ArrayObject([]) # no border
|
|
440
|
+
sig[NameObject("/IC")] = ArrayObject([]) # transparent fill
|
|
441
|
+
sig[NameObject("/BS")] = DictionaryObject({
|
|
442
|
+
NameObject("/W"): FloatObject(0),
|
|
443
|
+
})
|
|
444
|
+
sig[NameObject("/Q")] = NumberObject(2) # 0=left, 1=center, 2=right
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
Notes:
|
|
448
|
+
|
|
449
|
+
- `/DA` font names are limited to PDF built-ins (`/Helvetica`,
|
|
450
|
+
`/Times-Roman`, `/Courier`). **Built-ins do not cover CJK** — for
|
|
451
|
+
Chinese / Japanese / Korean signatures, drop down to the overlay
|
|
452
|
+
route in §5.3.
|
|
453
|
+
- `/Q` is text alignment: 0/1/2 = left/center/right.
|
|
454
|
+
- Set `/IC` to `[r, g, b]` instead of `[]` if you want a coloured fill
|
|
455
|
+
behind the text (e.g. a yellow highlight).
|
|
456
|
+
|
|
457
|
+
### 5.3 Replace text via white-out + overlay (works with CJK)
|
|
458
|
+
|
|
459
|
+
PDF text lives inside compressed content streams; editing it in place
|
|
460
|
+
is impractical. The reliable approach is **white box on top of the
|
|
461
|
+
original + new text on top of the white box, all merged as an overlay
|
|
462
|
+
page**:
|
|
463
|
+
|
|
464
|
+
1. Locate the original text with `pdfplumber` (gives x0/x1/top/bottom).
|
|
465
|
+
2. Build an overlay page in `reportlab` with a white rectangle and the
|
|
466
|
+
replacement text.
|
|
467
|
+
3. Call `merge_page(overlay)` to stack the overlay above the original.
|
|
468
|
+
|
|
469
|
+
```python
|
|
470
|
+
import io
|
|
471
|
+
import pdfplumber
|
|
472
|
+
from reportlab.pdfgen import canvas
|
|
473
|
+
from reportlab.pdfbase import pdfmetrics
|
|
474
|
+
from reportlab.pdfbase.ttfonts import TTFont
|
|
475
|
+
from pypdf import PdfReader, PdfWriter
|
|
476
|
+
|
|
477
|
+
# 1. Find the source coordinates.
|
|
478
|
+
with pdfplumber.open("menu.pdf") as src:
|
|
479
|
+
pg = src.pages[0]
|
|
480
|
+
page_w, page_h = float(pg.width), float(pg.height)
|
|
481
|
+
target = next(w for w in pg.extract_words() if "胡麻豆腐" in w["text"])
|
|
482
|
+
# target = {"text": "胡麻豆腐", "x0": 54.75, "x1": 97.58,
|
|
483
|
+
# "top": 255.77, "bottom": 266.48, ...}
|
|
484
|
+
|
|
485
|
+
# Convert pdfplumber-top to reportlab-y (origin at page bottom):
|
|
486
|
+
rl_y_bottom = page_h - target["bottom"]
|
|
487
|
+
rl_y_top = page_h - target["top"]
|
|
488
|
+
|
|
489
|
+
# 2. Draw the overlay (white box + new text).
|
|
490
|
+
pdfmetrics.registerFont(TTFont(
|
|
491
|
+
"DroidSans", "/usr/share/fonts/truetype/droid/DroidSansFallbackFull.ttf",
|
|
492
|
+
))
|
|
493
|
+
packet = io.BytesIO()
|
|
494
|
+
c = canvas.Canvas(packet, pagesize=(page_w, page_h))
|
|
495
|
+
c.setFillColorRGB(1, 1, 1)
|
|
496
|
+
c.rect(target["x0"] - 2, rl_y_bottom - 2,
|
|
497
|
+
(target["x1"] - target["x0"]) + 4,
|
|
498
|
+
(rl_y_top - rl_y_bottom) + 4,
|
|
499
|
+
fill=1, stroke=0) # pad ~2pt to swallow ink fringes
|
|
500
|
+
c.setFont("DroidSans", 11)
|
|
501
|
+
c.setFillColorRGB(0.18, 0.12, 0.05) # match the original ink colour
|
|
502
|
+
c.drawString(target["x0"], rl_y_bottom + 2, "世东豆腐")
|
|
503
|
+
c.save()
|
|
504
|
+
packet.seek(0)
|
|
505
|
+
|
|
506
|
+
# 3. Merge the overlay into the original page.
|
|
507
|
+
reader = PdfReader("menu.pdf")
|
|
508
|
+
overlay = PdfReader(packet).pages[0]
|
|
509
|
+
writer = PdfWriter()
|
|
510
|
+
for i, page in enumerate(reader.pages):
|
|
511
|
+
if i == 0:
|
|
512
|
+
page.merge_page(overlay) # overlay stacks ABOVE original
|
|
513
|
+
writer.add_page(page)
|
|
514
|
+
with open("menu_patched.pdf", "wb") as fp:
|
|
515
|
+
writer.write(fp)
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
Coordinate cheat sheet:
|
|
519
|
+
|
|
520
|
+
```
|
|
521
|
+
pdfplumber top -> distance from page TOP (top axis)
|
|
522
|
+
reportlab y -> distance from page BOTTOM (bottom axis)
|
|
523
|
+
pypdf y -> distance from page BOTTOM (bottom axis)
|
|
524
|
+
|
|
525
|
+
reportlab_y = page_height - pdfplumber_top
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
Notes:
|
|
529
|
+
|
|
530
|
+
- Pad the white rectangle by 2-4pt on each side to swallow
|
|
531
|
+
anti-aliasing fringes on the original glyphs.
|
|
532
|
+
- For colour match, render the source page to PNG (use
|
|
533
|
+
`python -m scripts.render.page_rasterize`), sample the ink with any
|
|
534
|
+
colour picker, and divide each channel by 255 to get the reportlab
|
|
535
|
+
triplet (e.g. RGB(46, 30, 13) -> `(0.18, 0.12, 0.05)`).
|
|
536
|
+
- CJK text needs a TTF font registered via `TTFont(...)` — built-in
|
|
537
|
+
fonts only cover Latin-1.
|
|
538
|
+
- `merge_page(overlay)` stacks `overlay` **above** the original in the
|
|
539
|
+
content stream — that is what makes the white box hide the original
|
|
540
|
+
ink and the new text sit on top of the white box.
|
|
541
|
+
|
|
542
|
+
### 5.4 Common pitfalls
|
|
543
|
+
|
|
544
|
+
| Symptom | Likely cause | Fix |
|
|
545
|
+
|---|---|---|
|
|
546
|
+
| Annotation invisible when printing | `/F` flag missing or wrong | set `/F` to `4` (Print) |
|
|
547
|
+
| Sticky note disappears after a second pass | `/Annots` was overwritten, not appended | `list(page.get("/Annots") or [])` then append |
|
|
548
|
+
| Chinese characters render as boxes in `/FreeText` | built-in fonts don't cover CJK | switch to the overlay route in §5.3 |
|
|
549
|
+
| White box covers the wrong region | mixed up pdfplumber top vs reportlab y | `reportlab_y = page_h - pdfplumber_top` |
|
|
550
|
+
| Original ink shows through the edges of the white box | rectangle too tight | pad by 2-4pt on each side |
|
|
551
|
+
| Overlay text appears underneath the white box | `merge_page` direction reversed | call `original.merge_page(overlay)` so the overlay goes on top |
|
|
552
|
+
|
|
553
|
+
---
|
|
554
|
+
|
|
555
|
+
## 6. Workflows
|
|
556
|
+
|
|
557
|
+
### 5.1 Extract figures from a PDF
|
|
558
|
+
|
|
559
|
+
Fast path with poppler:
|
|
560
|
+
|
|
561
|
+
```bash
|
|
562
|
+
pdfimages -all invoice.pdf images/img
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
Detect-and-crop with pypdfium2 plus numpy:
|
|
566
|
+
|
|
567
|
+
```python
|
|
568
|
+
import pypdfium2 as pdfium
|
|
569
|
+
import numpy as np
|
|
570
|
+
|
|
571
|
+
def figures(pdf_path):
|
|
572
|
+
src_doc = pdfium.PdfDocument(pdf_path)
|
|
573
|
+
for i, pg in enumerate(src_doc):
|
|
574
|
+
bitmap = pg.render(scale=3.0)
|
|
575
|
+
arr = np.array(bitmap.to_pil())
|
|
576
|
+
non_white = np.any(arr != [255, 255, 255], axis=2)
|
|
577
|
+
# Plug your favourite contour finder in here.
|
|
578
|
+
yield i, non_white.sum()
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
### 5.2 Batch processing with error handling
|
|
582
|
+
|
|
583
|
+
```python
|
|
584
|
+
import glob, logging, os
|
|
585
|
+
from pypdf import PdfReader, PdfWriter
|
|
586
|
+
|
|
587
|
+
logging.basicConfig(level=logging.INFO)
|
|
588
|
+
log = logging.getLogger(__name__)
|
|
589
|
+
|
|
590
|
+
def merge(folder):
|
|
591
|
+
out_doc = PdfWriter()
|
|
592
|
+
for path in glob.glob(os.path.join(folder, "*.pdf")):
|
|
593
|
+
try:
|
|
594
|
+
for pg in PdfReader(path).pages:
|
|
595
|
+
out_doc.add_page(pg)
|
|
596
|
+
log.info("ok %s", path)
|
|
597
|
+
except Exception as exc: # noqa: BLE001
|
|
598
|
+
log.error("skip %s: %s", path, exc)
|
|
599
|
+
with open("merged.pdf", "wb") as fp:
|
|
600
|
+
out_doc.write(fp)
|
|
601
|
+
|
|
602
|
+
def dump_text(folder):
|
|
603
|
+
for path in glob.glob(os.path.join(folder, "*.pdf")):
|
|
604
|
+
try:
|
|
605
|
+
text = "".join(pg.extract_text() for pg in PdfReader(path).pages)
|
|
606
|
+
with open(path.replace(".pdf", ".txt"), "w", encoding="utf-8") as fp:
|
|
607
|
+
fp.write(text)
|
|
608
|
+
except Exception as exc: # noqa: BLE001
|
|
609
|
+
log.error("skip %s: %s", path, exc)
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
### 5.3 Crop pages
|
|
613
|
+
|
|
614
|
+
```python
|
|
615
|
+
from pypdf import PdfReader, PdfWriter
|
|
616
|
+
|
|
617
|
+
src_doc = PdfReader("invoice.pdf")
|
|
618
|
+
out_doc = PdfWriter()
|
|
619
|
+
|
|
620
|
+
pg = src_doc.pages[0]
|
|
621
|
+
pg.mediabox.left = 50
|
|
622
|
+
pg.mediabox.bottom = 50
|
|
623
|
+
pg.mediabox.right = 550
|
|
624
|
+
pg.mediabox.top = 750
|
|
625
|
+
out_doc.add_page(pg)
|
|
626
|
+
|
|
627
|
+
with open("invoice_cropped.pdf", "wb") as fp:
|
|
628
|
+
out_doc.write(fp)
|
|
629
|
+
```
|
|
630
|
+
|
|
631
|
+
---
|
|
632
|
+
|
|
633
|
+
## 7. Performance Tips
|
|
634
|
+
|
|
635
|
+
1. **Large PDFs** — stream pages with `pypdf`/`pypdfium2`, never load
|
|
636
|
+
the entire file in RAM. Use `qpdf --split-pages` to chunk.
|
|
637
|
+
2. **Text extraction** — `pdftotext -bbox-layout` is fastest for plain
|
|
638
|
+
text; `pdfplumber` is the right tool when you need tables;
|
|
639
|
+
`pypdf.extract_text()` is the slowest option for big documents.
|
|
640
|
+
3. **Image extraction** — `pdfimages` is faster than rendering each
|
|
641
|
+
page yourself; render only when you actually need the rasterised
|
|
642
|
+
pixels (e.g. for OCR or visual overlay).
|
|
643
|
+
4. **Form filling** — pre-validate the input config (the bundled
|
|
644
|
+
`geometry_lint` does this for the overlay path); for AcroForm,
|
|
645
|
+
trust `acroform_apply` to validate against the discovered schema.
|
|
646
|
+
5. **Memory management** — process pages in chunks:
|
|
647
|
+
|
|
648
|
+
```python
|
|
649
|
+
from pypdf import PdfReader, PdfWriter
|
|
650
|
+
|
|
651
|
+
def chunked(path, chunk=10):
|
|
652
|
+
src_doc = PdfReader(path)
|
|
653
|
+
total = len(src_doc.pages)
|
|
654
|
+
for start in range(0, total, chunk):
|
|
655
|
+
out_doc = PdfWriter()
|
|
656
|
+
for i in range(start, min(start + chunk, total)):
|
|
657
|
+
out_doc.add_page(src_doc.pages[i])
|
|
658
|
+
with open(f"chunk_{start // chunk}.pdf", "wb") as fp:
|
|
659
|
+
out_doc.write(fp)
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
---
|
|
663
|
+
|
|
664
|
+
## 8. Troubleshooting
|
|
665
|
+
|
|
666
|
+
### Encrypted PDFs
|
|
667
|
+
|
|
668
|
+
```python
|
|
669
|
+
from pypdf import PdfReader
|
|
670
|
+
|
|
671
|
+
src_doc = PdfReader("encrypted.pdf")
|
|
672
|
+
if src_doc.is_encrypted:
|
|
673
|
+
src_doc.decrypt("password")
|
|
674
|
+
```
|
|
675
|
+
|
|
676
|
+
### Corrupted PDFs
|
|
677
|
+
|
|
678
|
+
```bash
|
|
679
|
+
qpdf --check corrupted.pdf
|
|
680
|
+
qpdf --replace-input corrupted.pdf
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
### Scanned PDFs (no text layer)
|
|
684
|
+
|
|
685
|
+
```python
|
|
686
|
+
import pytesseract
|
|
687
|
+
from pdf2image import convert_from_path
|
|
688
|
+
|
|
689
|
+
def ocr(pdf_path):
|
|
690
|
+
return "".join(
|
|
691
|
+
pytesseract.image_to_string(img)
|
|
692
|
+
for img in convert_from_path(pdf_path)
|
|
693
|
+
)
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
---
|
|
697
|
+
|
|
698
|
+
## 9. Third-Party Library Licenses
|
|
699
|
+
|
|
700
|
+
| Library | License |
|
|
701
|
+
| ------------ | --------- |
|
|
702
|
+
| pypdf | BSD |
|
|
703
|
+
| pdfplumber | MIT |
|
|
704
|
+
| pypdfium2 | Apache/BSD |
|
|
705
|
+
| reportlab | BSD |
|
|
706
|
+
| pdf2image | MIT |
|
|
707
|
+
| Pillow | HPND (PIL) |
|
|
708
|
+
| poppler-utils | GPL-2 |
|
|
709
|
+
| qpdf | Apache |
|
|
710
|
+
| pdf-lib | MIT |
|
|
711
|
+
| pdfjs-dist | Apache |
|