Metadata-Version: 2.5
Name: superpdf
Version: 0.2.0
Summary: PDFs to Markdown, HTML or JSON on your computer: headings, tables, charts as data and OCR. Python wrapper for the superPDF CLI.
Project-URL: Homepage, https://superpdf.ai
Project-URL: Documentation, https://github.com/arjunprabhulal/superpdf/tree/main/python#readme
Project-URL: Source, https://github.com/arjunprabhulal/superpdf
Project-URL: Issues, https://github.com/arjunprabhulal/superpdf/issues
Project-URL: Changelog, https://github.com/arjunprabhulal/superpdf/blob/main/python/CHANGELOG.md
Author-email: Arjun Prabhulal <arjun.prabhulal@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: charts,langchain,llama-index,ocr,pdf,pdf-parser,pdf-to-markdown,rag,tables
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: nodejs-wheel-binaries>=22
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: llama-index
Requires-Dist: llama-index-core>=0.12; extra == 'llama-index'
Description-Content-Type: text/markdown

# superpdf (Python)

[![PyPI](https://img.shields.io/pypi/v/superpdf?style=flat-square&color=4338ca)](https://pypi.org/project/superpdf/) [![Python](https://img.shields.io/pypi/pyversions/superpdf?style=flat-square)](https://pypi.org/project/superpdf/) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-555555?style=flat-square)](LICENSE)

Read PDFs into Markdown, HTML or JSON on your computer: headings, tables, charts as data and OCR for scanned
pages. Nothing is uploaded.

This package is a thin Python wrapper around the [superPDF command-line tool](https://github.com/arjunprabhulal/superpdf)
(npm package `@superpdf/cli`), so you get exactly what `superpdf export` produces. Every superPDF tool is a typed
Python function (merge, split, extract, rotate, page numbers, watermark, protect, unlock, repair, Office to PDF,
pipelines and batches), and it includes a LangChain document loader and a LlamaIndex reader.

## Requirements

Python 3.10 or later on macOS, Linux or Windows. Nothing else: Node.js comes with the package through
[`nodejs-wheel-binaries`](https://pypi.org/project/nodejs-wheel-binaries/).

The first call installs the superPDF reader (`@superpdf/cli`, about 185 MB with its PDF engine and OCR language
data) from npm into your cache folder, once. To do that ahead of time, for example in a Docker image or before going offline:

```bash
python -c "import superpdf; superpdf.install_cli()"
```

## Install

```bash
pip install superpdf
pip install "superpdf[langchain]"      # with the LangChain loader
pip install "superpdf[llama-index]"    # with the LlamaIndex reader
uv add superpdf                        # in a uv project
```

Or run the command without installing anything:

```bash
uvx superpdf export report.pdf --output report.md
pipx run superpdf export report.pdf --output report.md
```

## Use

```python
import superpdf

markdown = superpdf.export("report.pdf")  # the whole document as Markdown
html = superpdf.export("report.pdf", "html")
structure = superpdf.export_json("report.pdf")  # pages, blocks with type and position, sections

for page in superpdf.export_pages("report.pdf"):  # Markdown per page
    print(page["page"], page["markdown"][:80])

superpdf.export("report.pdf", pages="1,3-5", tables="html", ocr=False)
```

| Option | Meaning |
|---|---|
| `format` | `"markdown"` (default), `"html"` or `"json"` |
| `pages` | A selection such as `"1,3-5"`; all pages when omitted |
| `tables` | `"html"` writes Markdown tables as HTML, keeping merged header cells (Markdown only) |
| `ocr` | `True` (default) reads scanned pages with OCR in 15 languages; `False` skips it |
| `timeout` | Seconds before giving up (default 600) |

Errors raise `superpdf.SuperPDFError` with superPDF's own message, for example `No file at report.pdf.`

### Every PDF tool

Every superPDF tool is a Python function: the same 18 tools as the MCP server and the local API, with the same
validation and results. Each returns a typed dict; outputs are always new files (an existing file is never
overwritten), and a call only touches the folders of the files you give it.

```python
import superpdf

superpdf.merge(["a.pdf", "b.pdf"], "combined.pdf")  # {"output": ..., "pages": 7, "bytes": ...}
superpdf.extract_pages("report.pdf", "1, 3-5", "selected.pdf")
superpdf.rotate_pages("scan.pdf", "upright.pdf", pages="2", angle=180)
superpdf.split("book.pdf", "chapters/", pages="1-10, 11-20")  # one PDF per range
superpdf.add_page_labels("report.pdf", "numbered.pdf", text="Page {page} of {total}")
superpdf.add_watermark("contract.pdf", "DRAFT", "draft.pdf")
superpdf.protect("payslip.pdf", "a long password", "locked.pdf")  # AES-256
superpdf.unlock("locked.pdf", "open.pdf", password="a long password")
superpdf.from_office("slides.pptx", "slides.pdf")  # needs LibreOffice

info = superpdf.info("report.pdf")  # pages, sizes, form fields, properties
text = superpdf.read_text("report.pdf", pages="1-2")  # the text layer, page by page
```

| Function | What it does | Returns |
|---|---|---|
| `info(path)` | Page count, page sizes and rotation, form fields, properties | `PdfInfo` |
| `list_files(folder=".")` | The PDFs in a folder | `Folder` |
| `read_text(path, pages=, max_chars=)` | The text layer, page by page | `Text` |
| `extract_structure(path, pages=, format=, max_chars=)` | Markdown, HTML or JSON plus the outline; OCR for scans | `Structure` |
| `merge(inputs, output)` | Combine PDFs in order | `Written` |
| `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` |
| `split(path, output_folder, pages=, mode="ranges"\|"pages")` | One PDF per range or per page | `SplitResult` |
| `add_page_labels(path, output, pages=, text="{page} / {total}")` | Page numbers or a footer | `Written` |
| `add_watermark(path, text, output, pages=)` | Stamp text such as DRAFT diagonally | `Written` |
| `remove_metadata(path, output)` | Strip document properties | `Written` |
| `repair(path, output)` | Rebuild a damaged PDF | `RepairResult` |
| `protect(path, password, output)` | Encrypt with AES-256 | `Written` |
| `unlock(path, output, password=)` | Decrypt with a password you know | `Written` |
| `from_office(path, output)` | Word, Excel, PowerPoint or OpenDocument to PDF (LibreOffice) | `OfficeResult` |
| `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` |

`pages` takes numbers and ranges such as `"1, 3-5"`. Pipeline and batch steps are dicts such as
`{"action": "rotate", "options": {"pages": "1", "angle": 90}}`; the actions are extract, remove, rotate, crop
(margin), scale (factor), flatten, labels, watermark and metadata-clear.

`superpdf.tools()` lists every tool with its JSON input schema, and `superpdf.run_tool(name, arguments, allow=[...])`
runs any of them by name, for tools added to the CLI before this package catches up.

### LangChain

```python
from superpdf.langchain import SuperPDFLoader

docs = SuperPDFLoader("report.pdf").load()  # one Document per page
docs[0].metadata  # {"source": "report.pdf", "page": 1}
```

### LlamaIndex

```python
from superpdf.llama_index import SuperPDFReader

docs = SuperPDFReader(tables="html").load_data("report.pdf")  # one Document per page
```

## Command line

The package installs a `superpdf` command that runs the full CLI (the same as `python -m superpdf`):

```bash
superpdf export report.pdf --output report.md
superpdf export report.pdf --tables html --output report.md
superpdf help
```

`uvx superpdf …` and `pipx run superpdf …` run it in a temporary environment, with nothing to install first.

## How it works

Each call runs `superpdf export` in a subprocess (no shell) with the bundled Node.js and reads its output as UTF-8.
The reader is `@superpdf/cli` at the version this package is tested with, installed once into your cache folder:
`~/Library/Caches/superpdf` on macOS, `~/.cache/superpdf` on Linux and `%LOCALAPPDATA%\superpdf\Cache` on Windows
(set `SUPERPDF_CACHE_DIR` to change it). To use your own build instead, set `SUPERPDF_BIN` to a `superpdf` command or
`superpdf.js`. The reader, its tables, charts and OCR are described in the
[main README](https://github.com/arjunprabhulal/superpdf#readme).

## License

[Apache-2.0](LICENSE).
