pdf-textlayer 0.1.0__tar.gz → 0.2.0__tar.gz

{pdf_textlayer-0.1.0 → pdf_textlayer-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdf-textlayer
-Version: 0.1.0
+Version: 0.2.0
 Summary: Add an invisible, searchable text layer to a PDF from OCR JSON (PyMuPDF).
 Keywords: pdf,ocr,searchable,textlayer,pymupdf,liteparse,accessibility
 Author: Vivek Patel
@@ -75,7 +75,7 @@ from pdf_textlayer import make_searchable_pdf, Options
 
 stats = make_searchable_pdf(
     "input.pdf",
-    "parsed.json",                       # path, or already-loaded dict
+    "parsed.json",                       # path, dict, raw JSON bytes, or ParsedPage[]
     "output.pdf",
     adapter="liteparse",                 # default
     options=Options(min_confidence=0.5, font="helv"),
@@ -84,6 +84,20 @@ print(stats)
 # {'pages': 19, 'ocr_pages': [1, 2, ..., 19], 'items_drawn': 7643}
 ```
 
+### Bytes in, bytes out (server / API use)
+
+Both the input PDF and the result can be raw `bytes`, so no temp files are needed:
+
+```python
+# In a FastAPI/Flask handler — uploaded_pdf is bytes, ocr is a parsed dict
+pdf_bytes, stats = make_searchable_pdf(uploaded_pdf, ocr)
+return Response(pdf_bytes, media_type="application/pdf")
+```
+
+Omit `output_pdf` (or pass `None`) to get a `(bytes, Stats)` tuple back; pass a path to write directly. `input_pdf` and the JSON `source` each accept a path *or* `bytes`.
+
+### Working from ParsedPage objects directly
+
 If you already have the OCR results in memory (e.g. from another library), build `ParsedPage` objects directly and skip the adapter:
 
 ```python

{pdf_textlayer-0.1.0 → pdf_textlayer-0.2.0}/README.md

@@ -50,7 +50,7 @@ from pdf_textlayer import make_searchable_pdf, Options
 
 stats = make_searchable_pdf(
     "input.pdf",
-    "parsed.json",                       # path, or already-loaded dict
+    "parsed.json",                       # path, dict, raw JSON bytes, or ParsedPage[]
     "output.pdf",
     adapter="liteparse",                 # default
     options=Options(min_confidence=0.5, font="helv"),
@@ -59,6 +59,20 @@ print(stats)
 # {'pages': 19, 'ocr_pages': [1, 2, ..., 19], 'items_drawn': 7643}
 ```
 
+### Bytes in, bytes out (server / API use)
+
+Both the input PDF and the result can be raw `bytes`, so no temp files are needed:
+
+```python
+# In a FastAPI/Flask handler — uploaded_pdf is bytes, ocr is a parsed dict
+pdf_bytes, stats = make_searchable_pdf(uploaded_pdf, ocr)
+return Response(pdf_bytes, media_type="application/pdf")
+```
+
+Omit `output_pdf` (or pass `None`) to get a `(bytes, Stats)` tuple back; pass a path to write directly. `input_pdf` and the JSON `source` each accept a path *or* `bytes`.
+
+### Working from ParsedPage objects directly
+
 If you already have the OCR results in memory (e.g. from another library), build `ParsedPage` objects directly and skip the adapter:
 
 ```python

{pdf_textlayer-0.1.0 → pdf_textlayer-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pdf-textlayer"
-version = "0.1.0"
+version = "0.2.0"
 description = "Add an invisible, searchable text layer to a PDF from OCR JSON (PyMuPDF)."
 readme = "README.md"
 license = "MIT"

{pdf_textlayer-0.1.0 → pdf_textlayer-0.2.0}/src/pdf_textlayer/core.py

@@ -20,7 +20,7 @@ import logging
 from collections.abc import Iterable
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, TypedDict
+from typing import TYPE_CHECKING, Any, TypedDict, overload
 
 import pymupdf
 
@@ -158,14 +158,37 @@ def _draw_box(
     return True
 
 
+def _open_pdf(input_pdf: str | Path | bytes) -> pymupdf.Document:
+    """Open a PDF from a path or raw bytes."""
+    if isinstance(input_pdf, bytes):
+        return pymupdf.open(stream=input_pdf, filetype="pdf")
+    return pymupdf.open(str(input_pdf))
+
+
+@overload
 def write_textlayer(
-    input_pdf: str | Path,
+    input_pdf: str | Path | bytes,
     pages: Iterable[ParsedPage],
     output_pdf: str | Path,
     *,
+    options: Options | None = ...,
+) -> Stats: ...
+@overload
+def write_textlayer(
+    input_pdf: str | Path | bytes,
+    pages: Iterable[ParsedPage],
+    output_pdf: None = ...,
+    *,
+    options: Options | None = ...,
+) -> tuple[bytes, Stats]: ...
+def write_textlayer(
+    input_pdf: str | Path | bytes,
+    pages: Iterable[ParsedPage],
+    output_pdf: str | Path | None = None,
+    *,
     options: Options | None = None,
-) -> Stats:
-    """Draw an invisible text layer onto ``input_pdf`` and save it to ``output_pdf``.
+) -> Stats | tuple[bytes, Stats]:
+    """Draw an invisible text layer onto ``input_pdf``.
 
     This is the low-level entry point: it takes already-normalized
     :class:`ParsedPage` objects, so any OCR source can be plugged in by
@@ -176,18 +199,20 @@ def write_textlayer(
     contribute no drawable boxes after filtering — are left untouched.
 
     Args:
-        input_pdf: Path to the source PDF.
+        input_pdf: Path to the source PDF, or raw PDF bytes.
         pages: Iterable of :class:`ParsedPage`. Order does not matter.
-        output_pdf: Where to write the result. Overwritten if it exists.
+        output_pdf: Where to write the result. If ``None`` (default), the
+            PDF bytes are returned instead of written to disk.
         options: Drawing options.
 
     Returns:
-        :class:`Stats` summarizing what was written.
+        If ``output_pdf`` is a path, :class:`Stats` summarizing what was
+        written. If ``output_pdf`` is ``None``, a tuple ``(pdf_bytes, stats)``.
     """
     opts = options or Options()
     pages_by_num: dict[int, ParsedPage] = {p.page_number: p for p in pages}
 
-    doc = pymupdf.open(str(input_pdf))
+    doc = _open_pdf(input_pdf)
     try:
         font = pymupdf.Font(opts.font)
         ocr_page_nums: list[int] = []
@@ -215,57 +240,89 @@ def write_textlayer(
                 ocr_page_nums.append(pageno)
                 items_drawn += drawn_on_page
 
-        # Plain save keeps the input PDF's structure intact (image streams,
-        # fonts, annotations) and just appends the overlay objects.
-        doc.save(str(output_pdf))
-
-        return Stats(
+        stats = Stats(
             pages=doc.page_count,
             ocr_pages=ocr_page_nums,
             items_drawn=items_drawn,
         )
+
+        # Plain save keeps the input PDF's structure intact (image streams,
+        # fonts, annotations) and just appends the overlay objects.
+        if output_pdf is None:
+            return doc.tobytes(), stats
+        doc.save(str(output_pdf))
+        return stats
     finally:
         doc.close()
 
 
+@overload
 def make_searchable_pdf(
-    input_pdf: str | Path,
-    source: str | Path | dict[str, Any] | Iterable[ParsedPage],
+    input_pdf: str | Path | bytes,
+    source: str | Path | dict[str, Any] | bytes | Iterable[ParsedPage],
     output_pdf: str | Path,
     *,
+    adapter: Adapter | str = ...,
+    options: Options | None = ...,
+) -> Stats: ...
+@overload
+def make_searchable_pdf(
+    input_pdf: str | Path | bytes,
+    source: str | Path | dict[str, Any] | bytes | Iterable[ParsedPage],
+    output_pdf: None = ...,
+    *,
+    adapter: Adapter | str = ...,
+    options: Options | None = ...,
+) -> tuple[bytes, Stats]: ...
+def make_searchable_pdf(
+    input_pdf: str | Path | bytes,
+    source: str | Path | dict[str, Any] | bytes | Iterable[ParsedPage],
+    output_pdf: str | Path | None = None,
+    *,
     adapter: Adapter | str = "liteparse",
     options: Options | None = None,
-) -> Stats:
+) -> Stats | tuple[bytes, Stats]:
     """Generate a searchable PDF from a raw PDF plus an OCR JSON source.
 
     This is the convenience entry point: it accepts a JSON path / dict /
-    pre-built iterable of :class:`ParsedPage`, runs it through the chosen
-    adapter, and writes the overlay.
+    raw bytes / pre-built iterable of :class:`ParsedPage`, runs it through
+    the chosen adapter, and writes the overlay.
 
     Args:
-        input_pdf: Path to the source PDF (scanned, native, or mixed).
+        input_pdf: Path to the source PDF, or raw PDF bytes.
         source: One of —
 
             * a path (``str`` / ``Path``) to a JSON file,
             * an already-loaded ``dict``,
+            * raw JSON ``bytes``,
             * or an iterable of :class:`ParsedPage` (in which case
               ``adapter`` is ignored).
-        output_pdf: Where to write the searchable PDF.
+        output_pdf: Where to write the result. If ``None`` (default), the
+            PDF bytes are returned instead of written to disk.
         adapter: An :class:`~pdf_textlayer.adapters.Adapter` instance or
             the name of a registered adapter. Defaults to ``"liteparse"``.
         options: Drawing options.
 
     Returns:
-        :class:`Stats` summarizing what was written.
+        If ``output_pdf`` is a path, :class:`Stats`. If ``output_pdf`` is
+        ``None``, a tuple ``(pdf_bytes, stats)``.
     """
     if _looks_like_pages(source):
-        return write_textlayer(input_pdf, source, output_pdf, options=options)  # type: ignore[arg-type]
+        return write_textlayer(input_pdf, source, output_pdf, options=options)  # type: ignore[arg-type,call-overload]
 
     from .adapters import get_adapter
 
     adp = get_adapter(adapter) if isinstance(adapter, str) else adapter
-    data = source if isinstance(source, dict) else json.loads(Path(source).read_text())  # type: ignore[arg-type]
-    return write_textlayer(input_pdf, adp.parse(data), output_pdf, options=options)
+
+    if isinstance(source, dict):
+        data: dict[str, Any] = source
+    elif isinstance(source, bytes):
+        data = json.loads(source)
+    else:
+        # str | Path → filesystem path containing JSON.
+        data = json.loads(Path(source).read_text())  # type: ignore[arg-type]
+
+    return write_textlayer(input_pdf, adp.parse(data), output_pdf, options=options)  # type: ignore[call-overload]
 
 
 def _looks_like_pages(source: Any) -> bool: