$ show ocrmypdf/OCRmyPDF
OCRmyPDF is a mature, production-grade command-line tool and Python library that adds searchable OCR text layers to scanned PDFs, producing PDF/A-compliant output by default. The system ingests PDFs or images, optionally deskews/cleans pages via unpaper, rasterizes with Ghostscript or pypdfium2, runs Tesseract OCR, grafts the recognized text into the original PDF using a plugin-based pipeline, and performs image optimization with pngquant/jbig2enc. It supports multiple output formats (PDF/A-1b, PDF/A-2b, plain PDF), a plugin system for replacing OCR engines, rasterizers, and progress bars, and includes a directory watcher for batch processing. Architecture is a modular Python CLI/library with external subprocess orchestration; core abstractions include typed OcrOptions (pydantic), Executor concurrency, FontProvider chains, and the OcrElement data model. The codebase is exceptionally well-tested with a comprehensive suite of unit, integration, and plugin-level tests, and demonstrates advanced patterns for PDF repair, cross-platform tool discovery, and atomic file operations.
The LLM identified 5 files worth highlighting for reuse:
A custom readers-writer lock with writer preference, implemented using threading primitives. It provides a fair locking mechanism that prevents writer starvation by queuing waiting writers ahead of new readers. This is used to protect global plugin state in the multi-threaded OCR pipeline. The lock is isolated (no internal OCRmyPDF imports) and can be extracted directly into any Python project needing a RWLock with non-trivial fairness guarantees.
A Windows-specific shim that locates Ghostscript and Tesseract executables by probing the Windows Registry, Program Files, and common installation directories. It wraps subprocess calls to automatically add the found paths to the process's PATH environment variable. This solves the recurring problem of external tool discovery on Windows without requiring system PATH modifications. The logic is self-contained and can be reused in any Python tool that depends on external executables on Windows.
Runtime monkey-patches for the fpdf2 library that work around a bug where fpdf2 sends oversized CMap blocks, causing Ghostscript to reject the generated PDF. The patch splits large CMap blocks into smaller chunks that Ghostscript can accept. This demonstrates non-obvious reverse-engineering of both fpdf2 and Ghostscript internals. While fragile by nature (depends on fpdf2 internals), the pattern of isolating and clearly documenting runtime workarounds is valuable for any project that must interoperate with imperfect libraries.
A MultiFontManager that selects fonts per word based on language and glyph coverage. It chains multiple FontProvider instances (built-in, system), uses Unicode block detection to determine script, and falls back to a default font. This design allows rendering OCR text in any script without requiring a single monolithic font. The manager is fully reusable in any Python project needing intelligent per-word font selection, especially multi-lingual document rendering.
Functions to repair page boundary boxes in PDFs, handling common corruptions: reversed corners (MediaBox with x0 > x1), exponential coordinates (e.g., 1e-308), and boxes that exceed parent boundaries. Returns a BoxRepair dataclass recording what was fixed. This logic is self-contained (depends only on pikepdf) and can be extracted into any PDF processing tool that needs to sanitize malformed page boxes before further operations.