# peasy-pdf

Python PDF toolkit — merge, split, rotate, compress, extract text, encrypt, decrypt, and 14 more operations. Powered by [pypdf](https://pypdf.readthedocs.io/).

> **Try the interactive tools at [peasypdf.com](https://peasypdf.com)** — [Merge PDF](https://peasypdf.com/tools/merge-pdf/), [Split PDF](https://peasypdf.com/tools/split-pdf/), [Compress PDF](https://peasypdf.com/tools/compress-pdf/)

## Install

```bash
pip install peasy-pdf
```

With extras:

```bash
pip install "peasy-pdf[cli]"     # CLI with typer + rich
pip install "peasy-pdf[mcp]"     # MCP server for AI assistants
pip install "peasy-pdf[api]"     # REST API client for peasypdf.com
pip install "peasy-pdf[all]"     # Everything
```

## Quick Start

```python
from peasy_pdf import merge, split, rotate, compress, info, extract_text

# Merge multiple PDFs
merged = merge("report1.pdf", "report2.pdf")

# Split into individual pages
pages = split("document.pdf")

# Split every 5 pages
chunks = split("document.pdf", every=5)

# Rotate all pages 90°
rotated = rotate("document.pdf", angle=90)

# Compress to reduce file size
compressed = compress("large-file.pdf")

# Get PDF info
pdf_info = info("document.pdf")
print(f"Pages: {pdf_info.pages}, Title: {pdf_info.title}")

# Extract text
text = extract_text("document.pdf", pages="1-3")
print(text.full_text)
```

## What You Can Do

### Page Manipulation

| Function | Description |
|----------|-------------|
| `merge()` | Merge multiple PDFs into one |
| `split()` | Split by page ranges or every N pages |
| `rotate()` | Rotate pages (90°, 180°, 270°) |
| `reorder()` | Reorder pages in any sequence |
| `reverse()` | Reverse the page order |
| `delete_pages()` | Remove specific pages |
| `extract_pages()` | Extract specific pages |
| `odd_even()` | Filter odd or even pages |
| `duplicate_pages()` | Duplicate specific pages |
| `insert_blank()` | Insert blank pages at positions |

### Document Operations

| Function | Description |
|----------|-------------|
| `compress()` | Compress PDF streams to reduce size |
| `resize()` | Resize pages to standard sizes (A4, Letter, etc.) |
| `crop()` | Crop page margins |
| `flatten()` | Flatten form fields (make non-editable) |

### Text & Metadata

| Function | Description |
|----------|-------------|
| `extract_text()` | Extract text with per-page breakdown |
| `info()` | Get page count, metadata, encryption status |
| `get_metadata()` | Read PDF metadata |
| `set_metadata()` | Update PDF metadata |
| `strip_metadata()` | Remove all metadata |

### Security

| Function | Description |
|----------|-------------|
| `encrypt()` | Add password protection |
| `decrypt()` | Remove password protection |

## Page Specs

All page-aware functions use 1-indexed page specs:

```python
rotate("doc.pdf", pages="1")       # Page 1 only
rotate("doc.pdf", pages="1,3,5")   # Pages 1, 3, and 5
rotate("doc.pdf", pages="2-5")     # Pages 2 through 5
rotate("doc.pdf", pages="1,3-5,8") # Mixed
rotate("doc.pdf", pages="all")     # All pages (default)
```

## Input Flexibility

Every function accepts `bytes`, `Path`, or `str` (file path):

```python
from pathlib import Path

# File path as string
result = info("document.pdf")

# pathlib.Path
result = info(Path("document.pdf"))

# Raw bytes (e.g., from an HTTP response)
pdf_bytes = response.content
result = info(pdf_bytes)
```

## Command-Line Interface

```bash
pip install "peasy-pdf[cli]"

peasy-pdf merge file1.pdf file2.pdf -o merged.pdf
peasy-pdf split doc.pdf --every 5 -o split_
peasy-pdf rotate doc.pdf --angle 90 -o rotated.pdf
peasy-pdf compress doc.pdf -o compressed.pdf
peasy-pdf info doc.pdf
peasy-pdf text doc.pdf --pages 1-3
peasy-pdf encrypt doc.pdf --password secret -o encrypted.pdf
peasy-pdf decrypt encrypted.pdf --password secret -o decrypted.pdf
peasy-pdf metadata doc.pdf --title "New Title" --author "Author" -o updated.pdf
```

## MCP Server (Claude, Cursor, Windsurf)

```bash
pip install "peasy-pdf[mcp]"
```

Configure in Claude Desktop:

```json
{
    "mcpServers": {
        "peasy-pdf": {
            "command": "uvx",
            "args": ["--from", "peasy-pdf[mcp]", "python", "-m", "peasy_pdf.mcp_server"]
        }
    }
}
```

## REST API Client

```python
from peasy_pdf.api import PeasyPdfAPI

api = PeasyPdfAPI()
tools = api.list_tools()
glossary = api.search("compress")
```

## Learn More About PDF

- **Tools**: [Merge PDF](https://peasypdf.com/tools/merge-pdf/) · [Split PDF](https://peasypdf.com/tools/split-pdf/) · [Compress PDF](https://peasypdf.com/tools/compress-pdf/)
- **Guides**: [PDF Glossary](https://peasypdf.com/glossary/) · [PDF Guides](https://peasypdf.com/guides/)
- **API**: [Developer Docs](https://peasypdf.com/developers/) · [OpenAPI Spec](https://peasypdf.com/api/openapi.json)

## Peasy Developer Tools

| Package | PyPI | Description |
|---------|------|-------------|
| **peasy-pdf** | [PyPI](https://pypi.org/project/peasy-pdf/) | PDF merge, split, compress, 21 operations — [peasypdf.com](https://peasypdf.com) |
| peasytext | [PyPI](https://pypi.org/project/peasytext/) | Text case, slug, word count, 15 operations — [peasytext.com](https://peasytext.com) |

## License

MIT
