Add pypdf-compatible wrapper powered by LiteParse

[hexapode]

Summary

This PR introduces a new liteparse-pypdf-compatible package that provides a drop-in replacement for the pypdf library. The wrapper enhances text extraction using LiteParse's spatial reconstruction engine while delegating all other PDF operations (metadata, images, annotations, form fields, etc.) to the underlying pypdf library.

Key Changes

• New PdfReader class (_reader.py): A pypdf-compatible reader that combines LiteParse parsing for text extraction with pypdf's full feature set. Supports file paths, file-like objects, and bytes as input. Includes context manager support and proper cleanup of temporary files.

• New PageObject class (_page.py): A pypdf-compatible page wrapper that:

  • Uses LiteParse text extraction for superior spatial reconstruction
  • Delegates all other properties and methods to the underlying pypdf page
  • Provides fallback implementations for page dimensions and boxes when pypdf page is unavailable
  • Exposes LiteParse-specific extras like text_items and bounding_boxes

• Minimal _RectangleObject fallback: A lightweight rectangle implementation for page boxes when no pypdf page is available, supporting standard box properties (left, bottom, right, top, width, height) and indexing.

• Re-exports from pypdf: Makes commonly used pypdf classes available directly from liteparse_pypdf (PdfWriter, DocumentInformation, error classes) to minimize import changes for users.

• Comprehensive test suite (test_reader.py): 382 lines of tests covering:

  • PdfReader initialization, page access, and metadata delegation
  • PageObject text extraction, dimension handling, and fallback behavior
  • Visitor callbacks for text extraction
  • Page manipulation methods (scale, rotate)
  • Dict-like PDF dictionary access
  • RectangleObject properties and indexing
  • Re-export verification

• Documentation (README.md): Usage guide explaining the drop-in replacement approach, what's enhanced vs delegated, LiteParse-specific options, and available extras.

• Package configuration (pyproject.toml): Project metadata, dependencies (liteparse ≥1.0.0, pypdf ≥3.0.0), and development tools.

Notable Implementation Details

• Hybrid architecture: Text extraction always uses LiteParse for superior quality, while all other operations pass through to pypdf transparently
• Graceful degradation: PageObject works with or without an underlying pypdf page, providing fallbacks for basic properties
• Temporary file handling: Automatically manages temporary files when input is bytes or file-like objects, with proper cleanup via __del__ and context manager
• LiteParse configuration: Exposes OCR options (enabled, language, server URL) and rendering options (DPI, precise bounding boxes) at the reader level
• Full pypdf compatibility: Supports legacy method names (extractText, getPage, numPages) and all standard properties and methods

https://claude.ai/code/session_0115fTqokYpxd7kJY2j5wZwB