Metadata-Version: 2.5
Name: uploadkit-pdf
Version: 0.1.1
Summary: PDF validators, policies, and metadata for UploadKit
Project-URL: Homepage, https://github.com/uploadkit/uploadkit-pdf
Project-URL: Repository, https://github.com/uploadkit/uploadkit-pdf
Author: UploadKit
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: pdf,security,uploadkit,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pypdf>=5.0
Requires-Dist: uploadkit>=0.2.0
Provides-Extra: dev
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: uploadkit-testing>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# uploadkit-pdf

[![CI](https://github.com/uploadkit/uploadkit-pdf/actions/workflows/ci.yml/badge.svg)](https://github.com/uploadkit/uploadkit-pdf/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)](https://github.com/uploadkit/uploadkit-pdf/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)

PDF validators, policies, and metadata for UploadKit.

## What problem does this solve?

PDF-specific structure, security, and page-limit checks that plug into
`UploadPolicy.validators` without modifying UploadKit Core.

## When to use it

Use when uploads must accept PDFs safely (no JavaScript, embeds, or encryption
by default).

## When not to use it

- Do not render, edit, merge, or OCR PDFs here.
- Do not put generic MIME/filename checks here (see `uploadkit-security`).

## Installation

Requires **Python 3.10+**.

```bash
pip install uploadkit-pdf
```

## Quick Start

```python
from uploadkit import Uploader
from uploadkit_pdf import PdfPolicy

uploader = Uploader(PdfPolicy(max_size=5 * 1024 * 1024, max_pages=50), storage=my_storage)
```

### Customize validators

```python
from uploadkit import UploadPolicy
from uploadkit_pdf import default_pdf_validators, PdfPageLimitValidator

policy = UploadPolicy(
    allowed_extensions=frozenset({"pdf"}),
    allowed_mime_types=frozenset({"application/pdf"}),
    validators=default_pdf_validators(max_pages=20, exclude=PdfPageLimitValidator),
)
```

### Inspect metadata

```python
from uploadkit_pdf import inspect_pdf

meta = inspect_pdf(open("doc.pdf", "rb").read())
print(meta.page_count, meta.encrypted, meta.has_javascript)
```

## Public API

| Symbol | Kind |
|--------|------|
| `PdfPolicy` | Public |
| `PdfMetadata` / `inspect_pdf` | Public |
| `PdfStructureValidator` | Public |
| `PdfSecurityValidator` | Public |
| `PdfPageLimitValidator` | Public |
| `default_pdf_validators` | Public |
| `AsyncPdfStructureValidator` | Public |
| `AsyncPdfSecurityValidator` | Public |
| `AsyncPdfPageLimitValidator` | Public |
| `default_async_pdf_validators` | Public |

## Coverage

The coverage badge is a **measured** total from
`coverage report --include='src/*'`, not an aspirational 100%. CI enforces
`--fail-under=80`.

Most of the gap is defensive and format-variant code in `metadata.py`
(malformed PDFs, annotation/JS/embed edge cases). Validators and policies are
largely covered. Unlike Core / framework adapters, this package does not claim
100% yet — fixtures for those branches are welcome.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).
