Metadata-Version: 2.4
Name: pdf-form-tools
Version: 2.0.0
Summary: Template-aware tools for filling scanned PDF forms with visual verification
License-Expression: MIT
Project-URL: Homepage, https://github.com/ceratops-code/pdf-form-tools
Project-URL: Repository, https://github.com/ceratops-code/pdf-form-tools
Project-URL: Issues, https://github.com/ceratops-code/pdf-form-tools/issues
Keywords: pdf,forms,opencv,pymupdf,document-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Office/Business :: Office Suites
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: opencv-python-headless
Requires-Dist: pymupdf
Requires-Dist: pillow
Requires-Dist: pypdf
Requires-Dist: reportlab
Requires-Dist: python-bidi
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Dynamic: license-file

# pdf-form-tools

`pdf-form-tools` is an import-only Python package for filling layout-sensitive scanned PDF forms with deterministic placement helpers and visual verification primitives.

It is intentionally small:

- render PDF pages to raster images
- detect writable regions, checkbox boxes, signature lines, and ID slots
- draw text, checks, and signatures onto an overlay
- merge the overlay back into the original PDF

## Install

```bash
python -m pip install pdf-form-tools
```

## Example

```python
from pathlib import Path

from pdf_form_tools import Rect, merge_overlay_pdf, render_pdf_page

source_pdf = Path("form.pdf")
preview_png = Path("preview-page1.png")
render_pdf_page(source_pdf, 0, 2, preview_png)

# draw your overlay separately, then merge it back
merge_overlay_pdf(source_pdf, Path("overlay-page1.png"), Path("form-filled.pdf"))
```

## Development

```bash
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
python -m build
```

## Scope

This package contains reusable low-level helpers only. Form-specific filling flows belong in project-local scripts or thin runners, not in the shared library.
