Python PDF functions

Every PDF function in the superpdf Python package (superPDF AI for Python), with its options and what it returns.

Import the package and call a function: import superpdf, then superpdf.merge(…). Results are typed dicts (TypedDict), so editors and type checkers know their fields; Written is {"output", "pages", "bytes"}.

Read and compare

Function	What it does	Returns
`export(path, format="markdown", pages=, tables=, ocr=True)`	Markdown, HTML or JSON text: headings, tables, charts as data, OCR for scans	`str`
`export_json(path, …)`	The structure as a dict: title, pages with blocks, sections	`dict`
`export_pages(path, …)`	Markdown per page: `[{"page": 1, "markdown": …}]`	`list[dict]`
`info(path)`	Page count, page sizes and rotation, form fields, properties	`PdfInfo`
`list_files(folder=".")`	The PDFs in a folder, with sizes and dates	`Folder`
`read_text(path, pages=, max_chars=)`	The text layer, page by page (no OCR)	`Text`
`extract_structure(path, pages=, format=, max_chars=)`	Markdown, HTML or JSON plus the outline, capped at `max_chars`	`Structure`
`outline(path, format="markdown"\|"json")`	The outline, with the pages each section covers	`Outline`
`compare(before, after, max_chars=20000)`	The words that changed, page by page, marked `[-old-]` and `{+new+}`	`Comparison`

Read and compare: examples

Convert

Function	What it does	Returns
`to_docx(path, output, pages=)`	Editable Word: headings, bold and italic, lists, tables; OCR for scans	`WordResult`
`to_pptx(path, output, pages=)`	PowerPoint, one slide per page, text as text boxes	`SlidesResult`
`to_epub(path, output, title=, author=, language="en", split="headings"\|"pages")`	EPUB 3 e-book in chapters	`EpubResult`
`extract_tables(path, output, pages=, format="xlsx"\|"csv"\|"json"\|"markdown")`	Tables and vector charts; `output` ends in the format’s extension	`TablesResult`
`from_images(inputs, output)`	JPG or PNG images to PDF, one page each	`Written`
`from_markdown(path, output, page_size="A4"\|"Letter", title=)`	Typeset a Markdown file as a PDF	`Written`
`from_office(path, output)`	Word, Excel, PowerPoint or OpenDocument to PDF (needs LibreOffice)	`OfficeResult`

Convert: examples

Pages

Function	What it does	Returns
`merge(inputs, output)`	Combine PDFs in order	`Written`
`split(path, output_folder, pages=, mode="ranges"\|"pages")`	One PDF per range or per page; the folder is created if missing	`SplitResult`
`extract_pages(path, pages, output)`	Keep only some pages	`Written`
`remove_pages(path, pages, output)`	Drop pages	`Written`
`rotate_pages(path, output, pages=, angle=90\|180\|270)`	Rotate clockwise	`Written`
`resize_pages(path, output, mode="crop"\|"scale", pages=, margin=24, factor=1)`	Crop a margin (points) from each edge, or scale	`Written`

Pages: examples

Edit and protect

Function	What it does	Returns
`add_page_labels(path, output, pages=, text="{page} / {total}", position="bottom"\|"top")`	Page numbers, a footer or a header	`Written`
`add_watermark(path, text, output, pages=)`	Stamp text such as DRAFT diagonally (up to 60 characters)	`Written`
`add_text(path, text, output, pages=, x=36, y=36, size=12)`	Draw text such as a typed signature (points from the bottom-left corner)	`Written`
`fill_form(path, values, output, flatten=False)`	Fill form fields by name (`info` lists them)	`Written`
`flatten(path, output)`	Make form fields part of the page	`Written`
`remove_metadata(path, output)`	Strip document properties	`Written`
`repair(path, output)`	Rebuild a damaged PDF; `fixed` lists what was repaired	`RepairResult`
`protect(path, password, output)`	Encrypt with AES-256	`Written`
`unlock(path, output, password=)`	Decrypt with a password you know; never guesses	`Written`

Edit and protect: examples

Automate

Function	What it does	Returns
`run_pipeline(path, steps, output)`	Up to 10 steps on one PDF, saved once	`Written`
`run_batch(inputs, steps, output_folder, suffix=)`	The same steps on up to 50 PDFs; failures listed, not raised	`BatchResult`
`tools()`	Every tool with its JSON input schema	`list[dict]`
`run_tool(name, arguments, allow=[…])`	Run any tool by name, with the folders it may use	the tool’s result

Automate: examples

Arguments

Paths are strings or pathlib.Path; relative paths are relative to the current folder.
pages takes numbers and ranges such as "1, 3-5"; all pages when omitted.
Outputs must not exist yet; superPDF never overwrites a file. Folders for split and run_batch are created when missing.
Options you leave out take the tool’s default, shown above.
timeout (seconds) is accepted by the longer-running functions: 600 by default, 1800 for run_batch.

The same reference is in the package’s README on GitHub.