Encrypt for Certificate Recipients

from pathlib import Path

from cryptography import x509
from aspose_pdf import Document, Recipient

auditor = x509.load_pem_x509_certificate(Path("auditor.pem").read_bytes())
reviewer = x509.load_pem_x509_certificate(Path("reviewer.pem").read_bytes())

with Document("report.pdf") as document:
    document.encrypt_for_recipients([
        Recipient(auditor),                      # every permission
        Recipient(reviewer, permissions=-3844),  # read and print only
    ])
    document.save("report-sealed.pdf")

# Opening needs the certificate and its private key, not a password.
with Document("report-sealed.pdf", certificate=auditor, private_key=key) as doc:
    print(doc.page_count, doc.permissions)

Put a Contents Page in Front of a Report

from aspose_pdf import Document

with Document("report.pdf") as document:
    pages = document.add_table_of_contents(at=1)   # after the cover
    document.generate_outlines()                   # and bookmarks from the same headings
    print(f"contents on page {pages[0] + 1}")
    document.save("report-with-contents.pdf")

Create Bookmarks from Section Numbers or Invoice Labels

from aspose_pdf import Document

with Document("report.pdf") as document:
    count = document.generate_outlines_from_text(
        r"(?m)^Chapter \d+: (?P<title>[^\n]+)$",
        regex=True,
        title_group="title",
        replace=False,
    )
    document.save("report-with-bookmarks.pdf")

Each match creates a flat bookmark to its page. Strings are literal by default; compiled text regexes keep their flags. pages, clip, exclude_regions and skip_artifacts select the source text, and max_count caps created entries. replace=True (the default) replaces the tree, even when no titles match; replace=False appends. All matches and limits are checked before outline edits.

Sign a Document

from pathlib import Path

from cryptography.hazmat.primitives.serialization import pkcs12
from aspose_pdf import Document

key, certificate, chain = pkcs12.load_key_and_certificates(
    Path("signer.p12").read_bytes(), b"p12-password"
)

with Document("contract.pdf") as document:
    document.sign(
        "Approval",                      # an unsigned signature field; omit for an invisible one
        certificate=certificate,
        private_key=key,
        extra_certificates=chain,
        reason="Approved",
        pades=True,
        timestamp_url="http://timestamp.example/rfc3161",  # PAdES-T
    )
    document.add_ltv()                   # the chain and revocation data into /DSS: PAdES-LT
    document.add_document_timestamp(timestamp_url="http://timestamp.example/rfc3161")  # PAdES-LTA
    document.save("contract-signed.pdf")  # each step is an appended revision
    print([signature.valid for signature in document.signatures])

Make the Signature Visible

from pathlib import Path

from aspose_pdf import Document, SignatureAppearance

with Document("contract.pdf") as document:
    document.sign(
        "Approval",
        certificate=certificate,
        private_key=key,
        reason="I approve this document",
        location="Prague",
        appearance=SignatureAppearance(
            image=Path("signature-scan.png"),   # beside the text; "background" puts it behind
            border_color="#204060",
            background="#eef2f7",
        ),
    )
    document.save("contract-signed.pdf")

Put a Watermark on a Layer, Then Resolve It

from aspose_pdf import Document

with Document("report.pdf") as document:
    draft = document.layers.add("Draft", visible=False)
    with document.pages[0].layer(draft):
        document.pages[0].add_text("DRAFT", 150, 400, font_size=64)
    document.save("with-layers.pdf")

    # ...and when the file has to leave: hidden means gone, not merely hidden.
    document.layers["Draft"].visible = False
    document.flatten_layers()
    document.save("final.pdf")

Convert a Document to HTML or Markdown

from aspose_pdf import Document

with Document("report.pdf") as document:
    document.save_as_markdown("report.md")
    # Images as files in report_files/ rather than data: URIs; one HTML file per page.
    document.save_as_html("report.html", resources_directory="report_files", split_into_pages=True)
    print(document.to_markdown(pages=[0], markdown_format="CommonMark"))

Extract Tables as Lists or CSV

from aspose_pdf import Document

with Document("report.pdf") as document:
    for number, table in enumerate(document.extract_tables(pages=[0, 1]), 1):
        print(table.page_index, table.to_list())  # Zero-based source page; all rows retained.
        table.save_csv(f"tables/table-{number}.csv", overwrite=False)
        # table.to_csv(delimiter=";") returns a string without writing a file.

The detector shares the HTML/Markdown export's limits: no OCR or multiline-cell reconstruction, and ambiguous page columns can be mistaken for tables or divide a grid. See supported-features.md for the detailed extraction contract.

Build a Table

from aspose_pdf import Document, PageSize, Table

table = Table(column_widths=[220, 70, 90], padding=5,
              header_background_color="#003366", header_text_color=(1, 1, 1))
table.add_header_row(["Item", "Qty", "Price"])
table.add_row(["Widget, the larger kind", "2", "9.99"])
table.add_row(["Grommet", "14", "0.40"])
total = table.add_row()
total.add_cell("Total", column_span=2, alignment="right")
total.add_cell("14.38", alignment="right")

with Document() as document:
    page = document.pages.add(PageSize.A4)
    placement = page.add_table(table, 60, 760)   # continues onto new pages if needed
    page.add_text("Thank you", 60, placement["bottom"] - 24)
    document.save("invoice.pdf")

Draw Paths and Hold a Graphics State

from aspose_pdf import Document, GraphicsPath

with Document() as document:
    page = document.pages.add()

    dial = GraphicsPath().circle(300, 500, 80)
    page.draw_path(dial, fill_color="#eef3f8", stroke_color=(0.2, 0.3, 0.4), line_width=2)

    needle = GraphicsPath().move_to(300, 500).curve_to(320, 540, 340, 555, 360, 560)
    page.draw_path(needle, stroke_color="#cc3300", line_width=4, line_cap="round")

    page.draw_rectangle(220, 400, 160, 40, stroke_color=(0.4, 0.4, 0.4), dash=[4, 2])

    # The state applies to everything in the block — text included.
    with page.graphics(transform=(0, 1, -1, 0, 120, 300), opacity=0.6):
        page.add_text("rotated and faded", 0, 0, font_size=16)

    document.save("drawing.pdf")

Export a Page as SVG

from aspose_pdf import Document

with Document("report.pdf") as document:
    document.pages[0].save_as_svg("page-1.svg")
    document.save_as_svg("report.svg")  # one file per page: report-1.svg, ...

    # text="both" keeps the glyph outlines and puts selectable <text> over them,
    # so the page looks identical and its words can be searched and copied.
    # text="text" writes the words instead of the curves: far smaller, and the
    # glyph shapes become whatever font the viewer resolves the name to.
    document.pages[0].save_as_svg("page-1-selectable.svg", text="both")

Render a Page Whose Fonts Are Not Embedded

from aspose_pdf import Document, FontSubstitutionOptions

with Document("report-cjk.pdf") as document:
    # Use the machine's own fonts; FontSubstitutionOptions(["/opt/fonts"]) or
    # FontSubstitutionOptions(fonts={"SimSun": data}) keep it reproducible.
    document.font_substitution = FontSubstitutionOptions.system()
    document.save_page_as_image(0, "page-1.png", dpi=144)

Strip a Document Before Sending It

from aspose_pdf import Document

with Document("contract.pdf") as document:
    report = document.sanitize()          # add links=True, forms=True to go further
    print(report)
    # removed 7 metadata entries, 1 scripts, 3 actions, 1 attachments, 2 comments
    document.save("contract-clean.pdf")   # a full rewrite: the old revision does not survive

See What Fonts a Document Uses

from aspose_pdf import Document

with Document("report.pdf") as document:
    for font in document.fonts:
        print(font)
    # Arial (TrueType, embedded TrueType) on pages 1, 2
    # Helvetica (Type1, not embedded) on pages 2, 3

    missing = [f.name for f in document.fonts if not f.embedded]
    weight = sum(f.stored_bytes or 0 for f in document.fonts)

Put a Missing Font Into the Document

from aspose_pdf import Document, FontSubstitutionOptions

with Document("names-arial.pdf") as document:
    unsupplied = document.embed_fonts(sources=FontSubstitutionOptions.system())
    for message in unsupplied:          # empty when every font now has a program
        print(message)
    document.convert_to_pdfa("2b")
    document.save("archival.pdf")

Author Multi-Script Unicode Text

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Latin Č · Кириллица · Ελληνικά · 漢字",
        x=72,
        y=720,
        font="NotoSans-Regular.ttf",
    )
    document.save("unicode.pdf")

Author Complex-Script Text With TextLayoutOptions

from aspose_pdf import Document, TextLayoutOptions

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "English العربية 123",
        x=72,
        y=720,
        font_size=16,
        font="NotoSansArabic-Regular.ttf",
        layout=TextLayoutOptions(
            fallback_fonts=["NotoSans-Regular.ttf"],
            max_width=300,
            alignment="start",
            language="ar",
        ),
    )
    document.save("complex-text.pdf")

Extract Text From a PDF

from aspose_pdf import PdfExtractor

with PdfExtractor() as extractor:
    extractor.bind_pdf("input.pdf")
    extractor.extract_text()
    print(extractor.get_text())

To read a header, table cell, or invoice field, pass a rectangle in unrotated PDF coordinates (lower-left origin):

from aspose_pdf import Document

with Document("input.pdf") as document:
    print(document.pages[0].extract_text(clip=(72, 650, 300, 750)))

Document.extract_text(pages=[2, 0, 2]) reads the third, first, then third page. Indices in Document and TextExtractorOptions(pages=...) start at zero; the facade uses PdfExtractor.extract_text(page_numbers=[3, 1, 3]) instead. None selects all pages and [] selects none. Lists, ranges and generators preserve their order and repetitions. Use Document.open_streaming(...) to decode only selected page content.

Document.extract_text(clip=...), PdfExtractor.extract_text(clip=...), and TextExtractorOptions(clip=...) apply the rectangle to each selected page. Selection uses overlapping glyph bounds; see coverage and limitations.

Pass skip_artifacts=True to Document.extract_text, Page.extract_text, PdfExtractor.extract_text, or TextExtractorOptions to omit explicitly marked /Artifact content, such as tagged headers, footers, page numbers and watermarks:

with Document("input.pdf") as document:
    print(document.extract_text(pages=[0, 1], skip_artifacts=True))

The default is False. Untagged content is retained; filtering relies on PDF tags and does not guess which text is decorative. The option combines with page selection and clip and leaves the PDF unchanged.

To omit untagged headers, footers or sidebars, pass exclude_regions to the same four APIs. Rectangles use unrotated PDF coordinates and apply to each selected page; exclusions take priority over clip:

with Document("report.pdf") as document:
    text = document.extract_text(
        exclude_regions=[(0, 760, 612, 842), (0, 0, 612, 65)],
        skip_artifacts=True,
    )

Overlapping glyphs are omitted, with separators between retained pieces. Nonempty exclusions require measurable text, like clip; they do not perform OCR or redact the PDF. None and empty iterables preserve ordinary extraction.

Make Existing URLs and Email Addresses Clickable

from aspose_pdf import Document

with Document("input.pdf") as document:
    result = document.auto_link(pages=[0, 1])
    print(result.linked_count, result.skipped_count, result.existing_count)
    document.save("linked.pdf")

Page.auto_link() processes one page. Both methods recognize HTTP(S), www. and common email addresses, preserve text and skip addresses covered by an existing link. urls=False or emails=False disables either kind; max_count limits addresses considered. Uncertain coordinates are reported in skipped_fragments; see recognition and geometry limits.

Exchange Bookmarks as JSON

from aspose_pdf import Document

with Document("manual.pdf") as document:
    document.export_bookmarks_json("bookmarks.json")

with Document("updated-manual.pdf") as document:
    added = document.import_bookmarks_json("bookmarks.json", replace=True)
    print(f"Imported {added} bookmarks")
    document.save("with-bookmarks.pdf")

The versioned JSON preserves hierarchy, ordering, titles, styles, open state and supported targets. Page indices start at zero. Import appends by default; replace=True replaces the whole tree, and an empty replacement clears it. page_map={0: 2, 1: 3} remaps explicit local targets and must cover every source page used. Named local targets are exported as explicit page views by default; resolve_named_destinations=False retains their names without copying definitions. See bookmark exchange coverage for the schema, supported actions and validation limits.

Inventory PDF Links

from aspose_pdf import Document

with Document("manual.pdf") as document:
    for link in document.extract_links(pages=[0, 2]):
        print(link.page_index + 1, link.rect, link.action_type,
              link.resolved_uri, link.target_page_index, link.file, link.issues)

Audit outbound URLs, locate internal navigation and prepare link migrations without clicking through the PDF. Page.extract_links() inspects one page. Reports include direct targets and action chains, retain invalid targets with diagnostic codes, and remain usable after the document is closed. Source page and annotation indices are zero-based. Relative URLs use the catalog URI Base when present; remote file paths are reported as declared. No links are opened, files fetched or page content decoded. This inventories Link annotations, including hidden ones; bookmarks and URLs written only as page text are outside its scope. See link inventory details.

Update URLs Across a PDF

from aspose_pdf import Document

with Document("manual.pdf") as document:
    affected = document.replace_link_urls(
        "https://old.example/", "https://new.example/", dry_run=True,
    )
    document.replace_link_urls("https://old.example/", "https://new.example/")
    document.save("manual-with-updated-links.pdf")

The returned count is changed Link annotations, excluding no-op replacements. Use pages=[0, 2] or Page.replace_link_urls() to select pages. Strings replace literal substrings; regex=True or a compiled text regex supports capture-based replacement templates. Matching uses stored URLs, including relative or custom schemes. Only primary URI actions are edited; page text, bookmark URLs and action chains remain unchanged. The complete plan is checked before edits, with no page rendering, content decoding or network access.

Check Internal Links

from aspose_pdf import Document

with Document("manual.pdf") as document:
    for issue in document.validate_links():
        print(issue.source, issue.page_index, issue.annotation_index,
              issue.outline_path, issue.code, issue.message)

The report finds missing names/pages, malformed destinations and action chains, and cycles. Page and annotation indices start at zero. Use pages=[0, 2] to select link sources; bookmark and destination-definition checks remain enabled unless include_outlines=False or include_named_destinations=False is passed. External target reachability and full PDF conformance are outside these checks. See navigation validation coverage.

Clean Up Review Annotations by Author or Date

from aspose_pdf import Document

with Document("reviewed.pdf") as document:
    filters = {"authors": ["Alice"], "before": "2026-01-01"}
    print(document.remove_annotations(**filters, dry_run=True))
    removed = document.remove_annotations(**filters)
    document.save("cleaned.pdf")

Remove a previous review round or one reviewer's outdated notes before handoff. Filters combine with AND; author alternatives combine with OR. Date bounds are exclusive and default to modification dates; date_field="created" selects creation dates. Datetimes, dates, ISO strings and PDF date strings are accepted; naive dates/times use UTC. Missing or malformed annotation dates are preserved when filtering by date. case_sensitive=False enables Unicode author casefolding.

Default cleanup preserves links, widgets, file attachment icons and unknown subtypes. Owned popups count as removals; surviving replies are retained and detached from deleted parents. page.annotations.remove_matching() applies the same filters to one page. dry_run=True plans and validates without editing. Changes are in memory until saved. This removes review markup rather than physically erasing PDF objects or applying redactions. See cleanup details.

Exchange Annotations for Review

from aspose_pdf import AnnotationType, Document

with Document("reviewed.pdf") as document:
    document.export_annotations_json(
        "review/comments.json", pages=[0],
        subtypes=[AnnotationType.TEXT, AnnotationType.HIGHLIGHT], overwrite=False,
    )
    for comment in document.pages[0].annotations.to_list(subtypes="Text"):
        print(comment["author"], comment["contents"], comment["rect"])

JSON carries versioned review data; appearance streams, executable actions and attachments are omitted. Import reviewed JSON into a clean copy of the same document:

with Document("clean-copy.pdf") as document:
    added = document.import_annotations_json("review/comments.json")
    print(f"Imported {added} annotations")
    document.save("review-restored.pdf")

Import appends to existing annotations; importing again adds another copy. Use page_map={0: 2} to move source page 0's comments onto destination page 2, or page.annotations.import_json(source) to import one source page onto a specific page. Widgets, links, media and unknown subtypes are refused because their required data is absent from the export. Links to records outside the JSON are omitted. See annotation exchange coverage for the schema and limits.

Export Review Comments as XFDF

from aspose_pdf import AnnotationType, Document

with Document("reviewed.pdf") as document:
    document.export_annotations_xfdf(
        "review/comments.xfdf",
        pages=[0, 2],
        subtypes=[AnnotationType.TEXT, AnnotationType.HIGHLIGHT],
    )
    page_xfdf = document.pages[0].annotations.export_xfdf()

The methods return UTF-8 XML bytes and can also write a file or binary stream. Export includes supported review types, metadata and geometry, with popup windows nested under selected comments. Names stay unique and replies reference selected targets. Other annotation types, rich text, appearance streams and embedded assets are omitted. XFDF import is not provided. See XFDF coverage for supported properties and limits.

Fill a Batch of Forms From One Template

from aspose_pdf import FileDataSource, FormFiller, FormFillerOptions

options = FormFillerOptions(
    [
        {"person.name": "Alice", "agree": True},
        {"person.name": "Bob", "agree": False},
    ],
    flatten=True,
).add_input(FileDataSource("template.pdf"))

for index, result in enumerate(FormFiller().process(options), 1):
    result.save(f"filled-{index}.pdf")

Every record starts from the original template; omitted fields keep its values. flatten=True bakes form fields while retaining other annotations. The default keeps fields editable. Records follow Form.fill() types and strict field-name handling; generators and mutable lists are snapshotted for reuse. Multiple templates produce results in input order, then record order. All PDFs are prepared before configured outputs are written, and results are retained in memory under resource limits. password= opens protected templates.

Validate a Filled Form

Check stored answers before delivering a completed form:

from aspose_pdf import Document

with Document("application.pdf") as document:
    document.form.fill({"person.name": "Alice"})
    issues = document.form.validate()
    if issues:
        for issue in issues:
            print(issue.field_name, issue.code, issue.message)
    else:
        document.save("completed.pdf")

The check reports required answers, text length limits and invalid selections without modifying the PDF. It does not execute JavaScript or verify signatures; see form validation coverage.

Run a Batch Workflow With the Plugin Layer

from aspose_pdf.lowcode import (
    ByteArrayDataSource, Converter, ConvertOptions, FileDataSource, Rotator, RotateOptions,
)

# Straighten a scan, keeping each page's existing rotation in account.
rotated = Rotator().process(
    RotateOptions(90).add_input(FileDataSource("scan.pdf")).add_output(FileDataSource("upright.pdf"))
)

# Then turn the result into one PNG per page.
pages = Converter().process(
    ConvertOptions("png", dpi=150).add_input(ByteArrayDataSource(rotated[0].to_array()))
)
for index, page in enumerate(pages):
    page.save(f"page-{index + 1}.png")

Merge PDF Files

from aspose_pdf import PdfFileEditor

with PdfFileEditor() as editor:
    if not editor.concatenate(["part-1.pdf", "part-2.pdf"], "merged.pdf"):
        raise RuntimeError(editor.last_exception)

Assemble Duplex Scans

Scan fronts and backs separately, then alternate their pages:

from aspose_pdf import Document

with Document("fronts.pdf") as fronts, Document("backs.pdf") as backs:
    with fronts.interleave(backs, reverse_other=True) as assembled:
        assembled.save("duplex.pdf")

Use reverse_other=True when the back-side scan runs from last sheet to first; the default keeps both inputs' order. Page counts must match by default. strict=False retains unmatched pages at the end without inserting blanks. The inputs stay unchanged; the new document keeps page resources, annotations, fields, labels and bookmark targets. See assembly details.

Extract Words with Coordinates

Read positioned words for region analysis, indexing or custom highlights:

from aspose_pdf import Document

with Document("input.pdf") as document:
    for word in document.pages[0].extract_words():
        print(word.text, word.bbox, word.page_index)

    selected = document.extract_words(
        pages=[0, 2], clip=(72, 650, 300, 750), skip_artifacts=True
    )

Each TextWord is an immutable snapshot with text, zero-based page_index, rect (also bbox) and quad. Coordinates are unrotated PDF points with a lower-left origin. The region selects whole overlapping words. Bounds use font metrics; unmeasurable runs and content-stream /ActualText replacement spans are omitted. No OCR or language-specific word segmentation is performed. See word extraction details.

Split at Text Markers

Separate a batch of invoices or reports at pages containing a heading:

from aspose_pdf import Document

with Document("batch.pdf") as document:
    parts = document.split_by_text(r"(?m)^Invoice\s+\d+", regex=True)
    try:
        for number, part in enumerate(parts, 1):
            part.save(f"part-{number:03d}.pdf")
    finally:
        for part in parts:
            part.dispose()

Strings are literal substrings by default; compiled text regexes also work. Each matching page starts a part, with preceding pages kept separately unless include_preamble=False. No matches raises PdfValidationException. Matching uses extracted text, with optional case_sensitive=False; image-only scans need a text layer. See splitting details.

Split a Scan Batch at Blank Pages

from aspose_pdf import Document

with Document("batch.pdf") as document:
    parts = document.split_by_blank_pages()
    try:
        for number, part in enumerate(parts, 1):
            part.save(f"part-{number:03d}.pdf")
    finally:
        for part in parts:
            part.dispose()

Blank separator pages are excluded by default. With keep_separators=True, they stay at the end of the preceding part, with leading blanks in the first part. Consecutive separators do not create extra parts. Blank detection supports the same dpi, white_threshold, max_ink_ratio and include_annotations options as find_blank_pages(). An entirely blank batch produces no parts by default, or one copy when keeping separators. The source PDF is unchanged. See splitting details.

Find Visually Blank Pages

Find blank scanned sides from their rendered appearance:

from aspose_pdf import Document

with Document("scans.pdf") as document:
    blank_pages = document.find_blank_pages()
    print(blank_pages)  # Zero-based page indices; the document is unchanged.
    print(document.pages[0].is_blank())

    # Explicitly tolerate a small amount of scan noise.
    tolerant_matches = document.find_blank_pages(
        white_threshold=245, max_ink_ratio=0.0005, dpi=96
    )

The default checks at 72 DPI, treats RGB channels of 250 or more as white, and tolerates no darker pixels. Visible annotations count by default; include_annotations=False checks page content alone. This visual heuristic follows the shared renderer and may miss marks at the chosen resolution. Hidden text or other data can remain on a blank-looking page. See detection details.

Find Visually Duplicate Pages

Locate repeated scans or page views even when their PDF content differs:

from aspose_pdf import Document

with Document("batch.pdf") as document:
    groups = document.find_duplicate_pages(dpi=96)
    print(groups)  # For example: [[0, 3], [1, 4, 7]]; zero-based indices.

Each group includes its first occurrence. Pages must have equal raster dimensions and identical RGB pixels at the chosen DPI. Visible annotations count by default; include_annotations=False compares page content alone. Use pages=[0, 3, 7] to inspect a subset. The document is unchanged. This detects exact rendered matches; noisy scans can differ, and hidden data can differ on matching pages. See comparison details.

Find Images with Low Effective DPI

from aspose_pdf import Document

with Document("catalog.pdf") as document:
    for issue in document.find_low_resolution_images(min_dpi=150):
        print(issue.page_index + 1, issue.image_name,
              issue.dpi_x, issue.dpi_y, issue.bbox)

Find each placement below the threshold on either image axis, including reused images, inline images and nested forms, without decoding image pixels. Reports use zero-based page indices; pages=[2, 0] selects a subset. Rotation, shear and page UserUnit affect the calculation correctly. Hidden or clipped-out paints can be reported; this checks resolution rather than image sharpness or print certification. See resolution details.

Export PDF Images as ZIP

from aspose_pdf import Document

with Document("catalog.pdf") as document:
    document.export_images_zip("images.zip", include_manifest=True)
    selected = document.export_images_zip(pages=[2, 0])

Export photos, illustrations and scanned images in one step for reuse, content migration or downstream processing. Shared image objects are exported once; JPEG/JPEG 2000 keep their encoded payloads and other supported samples become PNG. Generated filenames are safe to unpack, and the optional manifest maps files to zero-based pages and resource paths. Export scans page and nested Form resources, including unused or hidden assets; it does not render pages, apply placement/clipping or combine transparency masks. Inline images and annotation appearances are excluded. The source is unchanged. See image ZIP details.

Export PDF Attachments as ZIP

from aspose_pdf import Document

with Document("report.pdf") as document:
    document.export_attachments_zip("attachments.zip", include_manifest=True)
    selected = document.export_attachments_zip(names=["data.csv", "notes.txt"])

The method returns ZIP bytes and optionally writes a file or binary stream. It preserves attachment contents, flattens paths into safe basenames, and renames collisions without losing files. The optional manifest.json maps archive names back to original PDF names and metadata. The PDF is unchanged; only document-level embedded files are included. See ZIP export details.

Import ZIP Files as PDF Attachments

from aspose_pdf import Document

with Document("report.pdf") as document:
    imported = document.import_attachments_zip("supporting-files.zip", on_conflict="rename")
    document.save("delivery-package.pdf")

Embed a batch of supporting documents without extracting temporary files. Input can also be ZIP bytes or a binary stream; names= selects exact archive members. The default restores names and metadata from the ZIP export manifest; use use_manifest=False for an unrelated manifest.json. Conflicts can fail, skip, replace or rename. Selected payloads are validated before attachments change. See ZIP import limits and formats.

Compare PDF Text Revisions

from aspose_pdf import Document

with Document("before.pdf") as before, Document("after.pdf") as after:
    for result in before.compare_text(after, ignore_whitespace=True):
        if not result.matches:
            print(result.unified_diff)

Pages are paired in order; use pages= and other_pages= for independent selections. Missing pages are reported explicitly. Reports retain the original extracted strings, while matching and diffs use the requested normalization. Use case_sensitive=False for Unicode case folding or skip_artifacts=True to omit explicitly tagged artifacts such as page numbers. Extraction needs a text layer and follows its reading-order limitations. It does not compare graphics, metadata or form values. Neither PDF is edited. See text comparison details.

Compare PDF Page Views

from aspose_pdf import Document

with Document("before.pdf") as before, Document("after.pdf") as after:
    results = before.compare_visual(after, dpi=96, include_diff_images=True)
    for pair, result in enumerate(results):
        if not result.matches:
            print(result.page_index, result.other_page_index,
                  result.difference_ratio, result.bbox)
            result.diff_image.save(f"diff-{pair + 1}.png")

Pages are paired in order, with missing pages reported when counts differ. Use pages= and other_pages= to select each side independently. Defaults require equal raster dimensions and identical RGB pixels. For scan noise, explicitly allow color differences with tolerance=3 and a changed area with max_diff_ratio=0.001. Neither PDF is edited. This compares rendered appearance at the chosen DPI, so hidden content and unsupported drawing can differ even when views match. See comparison details.

Exclude changing headers, dates or page numbers with ignore_regions:

with Document("before.pdf") as before, Document("after.pdf") as after:
    results = before.compare_visual(
        after, ignore_regions=[(0, 0, 612, 36)], include_diff_images=True,
    )

Rectangles use (left, top, right, bottom) in PDF points (1/72 inch), measured from the top-left of the displayed page after cropping and rotation. The same regions apply to both views and every selected pair, independently of DPI. Ignored pixels are excluded from counts, difference ratios and bounds; their union is reported as ignored_pixels and shown in light blue on diff images. Regions do not hide missing pages or unequal raster sizes and do not remove data from either PDF.

Measure Visible Content Without Cropping

from aspose_pdf import Document

with Document("scans.pdf") as document:
    for page_index, bounds in document.get_content_bounds(dpi=96).items():
        if bounds is not None:
            x0, y0, x1, y1 = bounds
            print(page_index + 1, x1 - x0, y1 - y0)
    first_page_bounds = document.pages[0].get_content_bounds()

Use measurements to review white margins and prepare crop or alignment decisions before changing the PDF. Bounds are (x0, y0, x1, y1) in unrotated page user coordinates, within the current CropBox; visually blank pages return None. The document method returns a dictionary keyed by zero-based page indices; pages=[2, 0] selects a subset. Visible annotations count unless include_annotations=False. Detection is approximate at the chosen DPI and shares the renderer's limits. See content bounds details.

Trim White Page Margins

Remove excess white space around scanned or drawn content:

from aspose_pdf import Document

with Document("scans.pdf") as document:
    for page in document.pages:
        page.auto_crop(margin=6, dpi=96)
    document.save("trimmed.pdf")

margin is padding in PDF points. Detection uses the current visible area, page rotation and visible annotations; blank-looking pages stay unchanged. Only CropBox changes: cropped-out content remains stored in the PDF. Detection is approximate at the chosen DPI; dark scan borders and speckles count as content. See cropping details.

Apply Resource Limits for Untrusted PDF Input

from aspose_pdf import Document, PdfLoadLimits, PdfResourceLimitException

limits = PdfLoadLimits(
    max_input_bytes=64 * 1024 * 1024,
    max_decoded_stream_bytes=16 * 1024 * 1024,
    max_image_pixels=25_000_000,
)

try:
    with Document(limits=limits) as document:
        document.load_from("input.pdf")
except PdfResourceLimitException as error:
    print(f"PDF rejected: {error}")

Core API

Annotations

Enumerations

Clustering

Engine

Generated

Security

Detailed Member Reference

Document Lifecycle

• Document
  • load_from(source, password, limits) -> Document / open_streaming(path, password, limits) -> Document
  • save(destination, save_format, overwrite) -> Document / merge() -> Document
  • optimize(options, compress_streams) -> Document (alias optimize_resources(options) -> Document)
  • encrypt(user_password, owner_password, permissions) -> Document / decrypt(password) -> Document / change_passwords(old_password, new_user_password, new_owner_password) -> Document
  • validate() -> bool / check() -> bool / repair() -> Document
  • validate_pdfa(level) -> PdfAValidationResult / convert_to_pdfa(level, font_lookup_directory) -> list[str]
  • add_table_of_contents(title, max_level, prefer_structure, at, size, margin, font_name, title_size, entry_size, indent, leader, links, page_numbers, tag) -> list[int]
  • sanitize(metadata, javascript, attachments, hidden_layers, comments, links, forms) -> SanitizationReport
  • save_as_svg(destination, pages, background, draw_annotations, font_substitution, precision, text, overwrite) -> list[Path]
  • fonts -> list[DocumentFont] (name, subtype, encoding, embedded, program size, pages)
  • embed_fonts(sources, directory) -> list[str]
  • validate_pdfua() -> PdfUaValidationResult / convert_to_pdfua(language, title, auto_tag) -> list[str] / auto_tag(image_alt) -> int
  • replace_text(search, replacement, page_index, case_sensitive, max_count) -> int / redact_text(search, page_index, case_sensitive, max_count, overlay, overlay_color) -> int
  • highlight_text(search, page_index, case_sensitive, max_count, regex, color, opacity, contents, title) -> TextHighlightResult
  • render_page(page_index, dpi, scale, background, antialias, shape_substitute_text, draw_annotations, font_substitution) -> RasterizedPage / save_page_as_image(page_index, destination, dpi, scale, background, antialias, mode, compression, quality, threshold) -> Path / save_as_tiff(destination, pages, dpi, scale, background, antialias, mode, compression, threshold) -> Path / save_as_svg(destination, pages, background, draw_annotations, font_substitution, precision, overwrite) -> list[Path]
  • render_contact_sheet(pages, columns, thumbnail_size, margin, spacing, labels, background, page_background, label_color, antialias, include_annotations) -> RasterizedPage / save_contact_sheet(destination, ..., mode, compression, quality, threshold, lossless, method, dither) -> Path
  • rasterized_copy(pages=None, dpi=150, background=(255, 255, 255), antialias=True, include_annotations=True, mode="rgb", threshold=128, dither=False) -> Document — create an independent image-only PDF from selected visible page views
  • split_spreads(pages=None, layout="horizontal", reverse=False, split_ratio=0.5, gutter=0, flatten_fields=True) -> Document — replace selected spreads with two cropped pages in an independent document
  • export_pages_zip(destination=None, pages=None, image_format="png", dpi=72, ..., include_manifest=False, overwrite=True) -> bytes — package selected rendered page views as image files with optional source-page metadata
  • compare_visual(other, pages, other_pages, dpi, tolerance, max_diff_ratio, include_annotations, include_diff_images, ignore_regions=None) -> list[PageVisualComparison]
  • compare_text(other, pages=None, other_pages=None, case_sensitive=True, ignore_whitespace=False, skip_artifacts=False) -> list[PageTextComparison] — review extracted page text revisions with normalized unified diffs
  • to_html(pages, title, embed_images, paragraph_gap, clip_to_page) -> str / to_markdown(pages, title, embed_images, markdown_format, paragraph_gap, clip_to_page) -> str / save_as_html(destination, pages, title, embed_images, split_into_pages, resources_directory, paragraph_gap, clip_to_page, overwrite) -> list[Path] / save_as_markdown(destination, pages, title, embed_images, image_directory, markdown_format, paragraph_gap, clip_to_page, overwrite) -> Path
  • flatten(fields=True, annotations=True, pages=None, strict=True) -> Document / generate_appearances(force) -> int / generate_field_appearances() -> int
  • split_by_bookmarks(level=1, include_preamble=True) -> list[Document] — split chapters at local bookmarks and retain leading pages in a separate document
  • export_bookmarks_json(destination=None, resolve_named_destinations=True, overwrite=True) -> bytes / import_bookmarks_json(source, replace=False, page_map=None) -> int — exchange a versioned bookmark tree, preserving supported targets and styles
  • split_by_text(pattern, regex=False, case_sensitive=True, include_preamble=True) -> list[Document] — split a batch at pages containing a literal or regular expression match
  • generate_outlines_from_text(pattern, pages=None, regex=False, case_sensitive=True, title_group=0, replace=True, max_count=0, clip=None, exclude_regions=None, skip_artifacts=False) -> int — create flat page bookmarks from extracted text matches and optional capture titles
  • split_by_blank_pages(keep_separators=False, dpi=72, white_threshold=250, max_ink_ratio=0, include_annotations=True) -> list[Document] — separate scan batches using visibly blank separator pages
  • interleave(other, reverse_other=False, strict=True) -> Document — alternate front/back scans into a new document, optionally reversing the back-side order
  • find_blank_pages(pages=None, dpi=72, white_threshold=250, max_ink_ratio=0, include_annotations=True) -> list[int] — find visually blank pages without modifying the document
  • get_content_bounds(pages=None, dpi=72, white_threshold=250, include_annotations=True) -> dict[int, tuple[float, float, float, float] | None] — measure visible content per selected page without cropping
  • find_duplicate_pages(pages=None, dpi=72, include_annotations=True) -> list[list[int]] — group pages with identical rendered views without deleting them
  • iter_pages() -> Iterator[Page] / iter_page_content_streams() -> Generator[bytes, None, None]
  • sync_metadata(direction) -> Document / add_attachment(name, content, mime, description, creation_date, mod_date, compress) -> Document
  • export_attachments_zip(destination=None, names=None, compression="deflate", compresslevel=6, include_manifest=False, overwrite=True) -> bytes
  • import_attachments_zip(source, names=None, on_conflict="error", use_manifest=True, compress=True) -> int
  • export_images_zip(destination=None, pages=None, compression="deflate", compresslevel=6, include_manifest=False, overwrite=True) -> bytes — package reusable image assets with optional page provenance
  • find_low_resolution_images(min_dpi=150, pages=None) -> list[ImageResolutionIssue] — locate image placements below the requested effective DPI before delivery
  • properties: pages, page_labels, form, outlines, layers, tagged_content, load_limits, xmp_metadata, embedded_files, page_count, info, is_encrypted, permissions, is_pdfua_compliant, font_substitution, page_mode, page_layout, open_action, viewer_preferences
  • add_stamp(stamp, pages) -> Document — stamp the pages named, or every page

Pages And Content

• Page
  • add_text(text, x, y, font_size, font_name, font, color, tag, actual_text, layout) -> Page
  • add_image(image, x, y, width, height, pixel_width, pixel_height, color_space, bits_per_component, name, tag, alt, actual_text) -> str
  • draw_rectangle(x, y, width, height, stroke_color, fill_color, line_width, tag, alt, actual_text) -> Page / draw_line(x1, y1, x2, y2, stroke_color, line_width, tag, alt, actual_text) -> Page
  • render(dpi, scale, background, antialias) -> RasterizedPage / save_as_image(path, dpi, scale, background, antialias) -> Path
  • is_blank(dpi=72, white_threshold=250, max_ink_ratio=0, include_annotations=True) -> bool — test the page's rendered appearance on white paper
  • auto_crop(margin=0, dpi=72, white_threshold=250, include_annotations=True) -> Page — trim white margins around rendered content by shrinking CropBox
  • get_content_bounds(dpi=72, white_threshold=250, include_annotations=True) -> tuple[float, float, float, float] | None — measure visible content without changing page boxes
  • add_stamp(stamp) -> Page — a text, image or page-number stamp over or under the page
  • replace_text(...) -> int / redact_text(...) -> int
  • highlight_text(...) -> TextHighlightResult — annotations and a report of unplaceable matches
  • properties: index, label, rect, media_box, crop_box, rotation, annotations, content
• PageCollection — item(index) -> Page, add(page) -> Page, insert(index, page) -> Page (the page may belong to another document, and is then imported with all it names), delete(index) -> None, clear() -> None, contains(page) -> bool, index_of(page) -> int
• PageLabelCollection (Document.page_labels) — a mutable mapping from the page a label range starts at to its PageLabel(style, prefix, start); NumberingStyle names the five styles and NONE; label(page_index) -> str | None, clear()

Text Extraction And Editing

• Document.highlight_text() / Page.highlight_text() find a phrase or regex and add highlight annotations. TextHighlightResult reports highlighted_count, skipped_count, matched_count, editable annotations, and skipped_fragments with text/page/offsets.

• Document.auto_link(pages=None, urls=True, emails=True, max_count=0) / Page.auto_link(urls=True, emails=True, max_count=0) create clickable addresses. AutoLinkResult reports linked_count, skipped_count, existing_count, matched_count, live annotations, skipped_fragments and existing_fragments.

• Document.replace_link_urls(search, replacement, pages=None, regex=False, case_sensitive=True, dry_run=False) / Page.replace_link_urls(search, replacement, regex=False, case_sensitive=True, dry_run=False) return the number of changed Link annotations, replacing primary URI URLs.

• Document.extract_text(pages=None, clip=None, skip_artifacts=False, exclude_regions=None) / Page.extract_text(clip=None, skip_artifacts=False, exclude_regions=None) return text, with zero-based page selection on Document, optionally selecting glyphs overlapping (x0, y0, x1, y1) in unrotated PDF space and excluding rectangular regions or explicitly marked Artifact content.

• Document.extract_words(pages=None, clip=None, skip_artifacts=False) / Page.extract_words(clip=None, skip_artifacts=False) return immutable TextWord snapshots with text, page index, rect/bbox and quad. A region selects whole overlapping words in unrotated PDF coordinates.

• Document.extract_tables(pages=None, clip_to_page=True) / Page.extract_tables(clip_to_page=True) return list[ExtractedTable]; pages contains zero-based indices. Each result exposes page_index, immutable rows / column_spans, row_count, column_count, to_list(), to_csv(delimiter=",") and save_csv(path, delimiter=",", encoding="utf-8", overwrite=True).

• Document.extract_blocks(pages=None, include_images=False, paragraph_gap=None, clip_to_page=True) / Page.extract_blocks(...) return list[ExtractedBlock] with immutable structure data, original page indices and unrotated PDF position anchors. Document.export_blocks_json(destination=None, ..., overwrite=True) / Page.export_blocks_json(...) return versioned UTF-8 JSON bytes and optionally write a path or binary stream.

  with Document("report.pdf") as document:
      for block in document.extract_blocks(pages=[0]):
          print(block.page_index, block.kind, block.text, block.rows)
      document.export_blocks_json("report-structure.json")
  

• PdfExtractor

  • bind_pdf(source, password, limits) -> None
  • extract_text(page_numbers=None, clip=None, skip_artifacts=False, exclude_regions=None) -> None (one-based selection) / get_text() -> str / has_next_page_text() -> bool / get_next_page_text() -> str
  • extract_image() -> None / has_next_image() -> bool / get_next_image() -> Any
  • extract_attachment() -> None / get_attachment(name) -> Any / get_attach_names() -> list[str]

• TextFragmentAbsorber / TextAbsorber — search exact phrases and regex patterns, collecting TextFragment results with page index, match offsets and, for a page of a document, where the text sits: rect, quads, font_name, font_size, color.

• PdfFileEditor

  • concatenate(inputs, output) -> bool
  • extract(source, destination, page_from, page_to) -> bool / insert(source, insert_file, destination, position) -> bool / delete(source, destination, pages_to_delete, page_to, page_from) -> bool / append(source, append_source, destination) -> bool / add_page_break(input_path, output_path) -> bool
  • property: last_exception: BaseException | None — the boolean-return / last_exception error contract this legacy facade keeps.

Forms And Annotations

• FormFillerOptions(records, strict=True, flatten=False, password=None, limits=None) / FormFiller.process(options) -> ResultContainer generate independent filled PDFs for each template/record pair. Add template data sources and optional paired outputs.

• Form

  • add_text_field(name, page, rect, value, font_size, multiline, alignment, read_only, required) -> Field
  • add_checkbox(name, page, rect, checked, on_value, read_only, required) -> Field / add_radio_group(name, page, options, value, read_only, required) -> Field
  • add_list_box(...) -> Field / add_combo_box(...) -> Field / add_push_button(name, page, rect, caption, read_only, required) -> Field
  • remove_field(name) -> Field / generate_appearances() -> int / flatten(fields=True, annotations=True, pages=None, strict=True) -> None
  • fill(values, strict=True) -> list[str] / to_dict() -> dict / export_json(destination=None) -> bytes / import_json(source, strict=True) -> list[str]
  • to_schema() -> dict / export_schema(destination=None, overwrite=True) -> bytes — versioned template descriptions with field types, effective constraints, choices and defaults.
  • reset(fields=None, strict=True) -> list[str] — restore all or selected fields to template defaults
  • validate(fields=None, strict=True) -> list[FormValidationIssue] — inspect stored answers without changing them
  • export_fdf(destination) -> bytes / export_xfdf(destination) -> bytes / import_fdf(source) -> list[str] / import_xfdf(source) -> list[str] (form data interchange)

• Field — remove() -> Field; properties name, value, field_type, partial_name, alternate_name, mapping_name, flags, read_only, required, no_export, default_value, max_length, multiline, password, comb, options, multi_select, editable, export_values, widgets (FieldWidget(page_index, rect)), page_index, rect Configuration setters include default_value, max_length, multiline, password, comb, options, multi_select and editable.

• FormValidationIssue — an immutable record with field_name, field_type, code and message; an empty validation report means no covered value issues.

• Annotation — generate_appearance(force) -> bool, get_property(name, default) -> Any, set_property(name, value) -> None; properties subtype, rect, contents, appearance_normal

• AnnotationCollection — add(subtype, rect, contents, title, appearance_normal, properties) -> Annotation, insert(...), delete(index) -> None, generate_appearances(force) -> int, to_list(subtypes=None) -> list[dict], export_json(destination=None, subtypes=None, overwrite=True) -> bytes, export_xfdf(destination=None, subtypes=None, overwrite=True) -> bytes, import_json(source) -> int

• Document.export_annotations_json(destination=None, pages=None, subtypes=None, overwrite=True) -> bytes exports all or selected annotations to a path, binary stream or UTF-8 bytes.

• Document.export_annotations_xfdf(destination=None, pages=None, subtypes=None, overwrite=True) -> bytes / Page.annotations.export_xfdf(destination=None, subtypes=None, overwrite=True) -> bytes exports supported review comments and markup as UTF-8 XFDF, optionally writing a path or stream.

• Document.remove_annotations(pages=None, authors=None, before=None, after=None, date_field="modified", subtypes=None, case_sensitive=True, dry_run=False) -> int / AnnotationCollection.remove_matching(...) -> int remove selected review annotations by metadata or return the planned count without edits.

• Document.import_annotations_json(source, page_map=None) -> int appends supported review annotations from a path, UTF-8 bytes or readable binary stream; returns the number added.

• Document.extract_links(pages=None) / Page.extract_links() return list[ExtractedLink] for link auditing, navigation review and content migrations.

• Document.validate_links(pages=None, include_outlines=True, include_named_destinations=True) / Page.validate_links() return list[LinkValidationIssue] without editing the PDF. Issues expose source, code, message, page_index, annotation_index, outline_path, destination_name and target_path.

Security And Signatures

• Document.encrypt(user_password, owner_password, permissions) / Document.decrypt(password) / Document.change_passwords(...)
• Document.sign(field=None, *, certificate, private_key, extra_certificates, reason, location, contact, signer_name, pades, timestamp_url, timestamp_authority, timestamp_timeout, certify, appearance), Document.add_ltv(certificates, crls, ocsp_responses), Document.add_document_timestamp(timestamp_url | timestamp_authority) — carried out by save() as appended revisions (PAdES-B/T/LT/LTA), after which Document.signatures lists them
• PdfSignature.validate(options) -> ValidationResult; properties valid, name, date, docmdp_level
• ValidationResult — properties is_valid, status, trust_status, revocation_status, certification_level, pades_level
• PdfLoadLimits — immutable resource policy; PdfLoadLimits.unlimited() disables every field; covers max_input_bytes, max_objects, max_decoded_stream_bytes, max_image_pixels, and 12 more bounded resources.

Low-Code Plugins

• Merger, Splitter, Optimizer, TextExtractor — each a PdfPlugin subclass exposing process(options) -> ResultContainer.
• FileDataSource, ByteArrayDataSource, StreamDataSource — DataSource implementations for path, in-memory bytes, and stream inputs/outputs.
• PluginOptions — holds the input/output DataSource lists plus the resource-limit policy shared by a plugin run.

Fonts

• FontRepository — add_source(source) -> None, get_available_fonts() -> list[FontDescriptor], find_font(font_name) -> FontDescriptor | None, open_font(font_name) -> bytes | None
• FontSource hierarchy — FolderFontSource, FileFontSource, MemoryFontSource, SystemFontSource

ci.yml runs a minimal-install job plus the same core checks on Python 3.11, 3.12, and 3.13; security-audit.yml runs a weekly pip-audit dependency scan; and packaging is exercised by publish-pypi.yml and publish-testpypi.yml, both manually triggered (workflow_dispatch), not run automatically on every push.