sigdetect 0.2.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

sigdetect/api.py

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, Generator, Iterable, Iterator, Literal
+from typing import Any, Generator, Iterable, Iterator, Literal, overload
 
 from sigdetect.config import DetectConfiguration
+from sigdetect.cropping import SignatureCrop
 from sigdetect.detector import BuildDetector, Detector, FileResult, Signature
 
 EngineName = Literal["pypdf2", "pypdf", "pymupdf"]
@@ -191,17 +192,45 @@ def detector_context(**kwargs: Any) -> Generator[Detector, None, None]:
         pass
 
 
+@overload
 def CropSignatureImages(
     pdfPath: str | Path,
     fileResult: FileResult | dict[str, Any],
     *,
     outputDirectory: str | Path,
     dpi: int = 200,
-) -> list[Path]:
+    returnBytes: Literal[False] = False,
+    saveToDisk: bool = True,
+) -> list[Path]: ...
+
+
+@overload
+def CropSignatureImages(
+    pdfPath: str | Path,
+    fileResult: FileResult | dict[str, Any],
+    *,
+    outputDirectory: str | Path,
+    dpi: int,
+    returnBytes: Literal[True],
+    saveToDisk: bool,
+) -> list[SignatureCrop]: ...
+
+
+def CropSignatureImages(
+    pdfPath: str | Path,
+    fileResult: FileResult | dict[str, Any],
+    *,
+    outputDirectory: str | Path,
+    dpi: int = 200,
+    returnBytes: bool = False,
+    saveToDisk: bool = True,
+) -> list[Path] | list[SignatureCrop]:
     """Crop detected signature regions to PNG files.
 
     Accepts either a :class:`FileResult` instance or the ``dict`` returned by
     :func:`DetectPdf`. Requires the optional ``pymupdf`` dependency.
+    Set ``returnBytes=True`` to also receive in-memory PNG bytes for each crop. Set
+    ``saveToDisk=False`` to skip writing PNG files while still returning in-memory data.
     """
 
     from sigdetect.cropping import crop_signatures
@@ -212,6 +241,8 @@ def CropSignatureImages(
         file_result=file_result_obj,
         output_dir=Path(outputDirectory),
         dpi=dpi,
+        return_bytes=returnBytes,
+        save_files=saveToDisk,
     )
     if original_dict is not None:
         original_dict.clear()

sigdetect/cropping.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import logging
 import re
+from dataclasses import dataclass
 from pathlib import Path
+from typing import Literal, overload
 
 from .detector.file_result_model import FileResult
 from .detector.signature_model import Signature
@@ -19,6 +21,29 @@ class SignatureCroppingUnavailable(RuntimeError):
     """Raised when PNG cropping cannot be performed (e.g., PyMuPDF missing)."""
 
 
+@dataclass(slots=True)
+class SignatureCrop:
+    """PNG crop metadata and in-memory content."""
+
+    path: Path
+    image_bytes: bytes
+    signature: Signature
+    saved_to_disk: bool = True
+
+
+@overload
+def crop_signatures(
+    pdf_path: Path,
+    file_result: FileResult,
+    *,
+    output_dir: Path,
+    dpi: int = 200,
+    logger: logging.Logger | None = None,
+    return_bytes: Literal[False] = False,
+) -> list[Path]: ...
+
+
+@overload
 def crop_signatures(
     pdf_path: Path,
     file_result: FileResult,
@@ -26,22 +51,44 @@ def crop_signatures(
     output_dir: Path,
     dpi: int = 200,
     logger: logging.Logger | None = None,
-) -> list[Path]:
-    """Render each signature bounding box to a PNG image using PyMuPDF."""
+    return_bytes: Literal[True] = True,
+) -> list[SignatureCrop]: ...
+
+
+def crop_signatures(
+    pdf_path: Path,
+    file_result: FileResult,
+    *,
+    output_dir: Path,
+    dpi: int = 200,
+    logger: logging.Logger | None = None,
+    return_bytes: bool = False,
+    save_files: bool = True,
+) -> list[Path] | list[SignatureCrop]:
+    """Render each signature bounding box to a PNG image using PyMuPDF.
+
+    Set ``return_bytes=True`` to collect in-memory PNG bytes for each crop while also writing
+    the files to ``output_dir``. Set ``save_files=False`` to skip writing PNGs to disk.
+    """
 
     if fitz is None:  # pragma: no cover - exercised when dependency absent
         raise SignatureCroppingUnavailable(
             "PyMuPDF is required for PNG crops. Install 'pymupdf' or 'sigdetect[pymupdf]'."
         )
+    if not save_files and not return_bytes:
+        raise ValueError("At least one of save_files or return_bytes must be True")
 
     pdf_path = Path(pdf_path)
     output_dir = Path(output_dir)
-    output_dir.mkdir(parents=True, exist_ok=True)
-    generated: list[Path] = []
+    if save_files:
+        output_dir.mkdir(parents=True, exist_ok=True)
+    generated_paths: list[Path] = []
+    generated_crops: list[SignatureCrop] = []
 
     with fitz.open(pdf_path) as document:  # type: ignore[attr-defined]
         per_document_dir = output_dir / pdf_path.stem
-        per_document_dir.mkdir(parents=True, exist_ok=True)
+        if save_files:
+            per_document_dir.mkdir(parents=True, exist_ok=True)
         scale = dpi / 72.0
         matrix = fitz.Matrix(scale, scale)
 
@@ -70,8 +117,12 @@ def crop_signatures(
             destination = per_document_dir / filename
 
             try:
+                image_bytes: bytes | None = None
                 pixmap = page.get_pixmap(matrix=matrix, clip=clip, alpha=False)
-                pixmap.save(destination)
+                if save_files:
+                    pixmap.save(destination)
+                if return_bytes:
+                    image_bytes = pixmap.tobytes("png")
             except Exception as exc:  # pragma: no cover - defensive
                 if logger:
                     logger.warning(
@@ -85,10 +136,22 @@ def crop_signatures(
                     )
                 continue
 
-            signature.CropPath = str(destination)
-            generated.append(destination)
+            if save_files:
+                signature.CropPath = str(destination)
+                generated_paths.append(destination)
+            if return_bytes:
+                if image_bytes is None:  # pragma: no cover - defensive
+                    continue
+                generated_crops.append(
+                    SignatureCrop(
+                        path=destination,
+                        image_bytes=image_bytes,
+                        signature=signature,
+                        saved_to_disk=save_files,
+                    )
+                )
 
-    return generated
+    return generated_crops if return_bytes else generated_paths
 
 
 def _to_clip_rect(page, bbox: tuple[float, float, float, float]):

{sigdetect-0.2.0.dist-info → sigdetect-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sigdetect
-Version: 0.2.0
+Version: 0.3.1
 Summary: Signature detection and role attribution for PDFs
 Author-email: BT Asmamaw <basmamaw@angeiongroup.com>
 License: MIT
@@ -192,14 +192,23 @@ for res in ScanDirectory(
 # 3) Crop PNG snippets for FileResult objects (requires PyMuPDF)
 detector = get_detector(pdfRoot="/path/to/pdfs", profileName="hipaa")
 file_result = detector.Detect(Path("/path/to/pdfs/example.pdf"))
-CropSignatureImages(
+crops = CropSignatureImages(
     "/path/to/pdfs/example.pdf",
     file_result,
     outputDirectory="./signature_crops",
     dpi=200,
+    returnBytes=True,  # also returns in-memory PNG bytes for each crop
+    # saveToDisk=False,  # optional: skip writing PNGs to disk
 )
+
+first_crop = crops[0]
+print(first_crop.path, len(first_crop.image_bytes))
 ~~~
 
+When ``returnBytes=True`` the helper returns ``SignatureCrop`` objects containing the saved path,
+PNG bytes, and the originating signature metadata.
+Pass ``saveToDisk=False`` if you only want in-memory PNG bytes (no files on disk or ``crop_path`` updates).
+
 
 ## Result schema
 

{sigdetect-0.2.0.dist-info → sigdetect-0.3.1.dist-info}/RECORD

@@ -1,8 +1,8 @@
 sigdetect/__init__.py,sha256=LhY78mDZ1ClYVNTxW_qtE-vqJoN9N7N5ZcNRDUI_3ss,575
-sigdetect/api.py,sha256=F7bM0ctYmtczjqSbsl7MkUZQ28wkRnLAYt1WxfCtzk4,8518
+sigdetect/api.py,sha256=6_CMSxcag9coHHzrpuRSVimHWSNtqQiWY9hdlqQ2IKY,9396
 sigdetect/cli.py,sha256=NctAnaB-TQrUAT9m-v8kj2_KTNs88kbFOCiX32tHZm8,7920
 sigdetect/config.py,sha256=S0NVKuJYiHJCocL-VNFdGJpasFcjTecavC4EthyS1DQ,5951
-sigdetect/cropping.py,sha256=89xPwXhWkJC5E0oW2e3_fDyERH5YGqyt4q4B-HSld4o,4084
+sigdetect/cropping.py,sha256=dmJF4Q1tkmkfm0NaiwHddNOP8Sj9S4Lj_d5EBjodEkk,6015
 sigdetect/eda.py,sha256=S92G1Gjmepri__D0n_V6foq0lQgH-RXI9anW8A58jfw,4681
 sigdetect/logging_setup.py,sha256=LMF8ao_a-JwH0S522T6aYTFX3e8Ajjv_5ODS2YiBcHA,6404
 sigdetect/utils.py,sha256=T9rubLf5T9JmjOHYMOba1j34fhOJaWocAXccnGTxRUE,5198
@@ -16,8 +16,8 @@ sigdetect/detector/file_result_model.py,sha256=j2gTc9Sw3fJOHlexYsR_m5DiwHA8DzIzA
 sigdetect/detector/pymupdf_engine.py,sha256=iyp7JuPlUnydwohH5zbNg4MwH44mBmxbBWOS3ZmArBo,17339
 sigdetect/detector/pypdf2_engine.py,sha256=INWQH06kMLvto2VS-EdLC-EtMC6AG7JmdVYmNgx6_RU,47313
 sigdetect/detector/signature_model.py,sha256=mztb9V5wgv2oohQ5Cxzcv8_Bo6TyWAVIXteaeQ2rywQ,1076
-sigdetect-0.2.0.dist-info/METADATA,sha256=HzF-CmGBs48_Cqv9Dv9AdXo_UoztA-tLPxVMN1fXOH0,11866
-sigdetect-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sigdetect-0.2.0.dist-info/entry_points.txt,sha256=iqtfKjBU44-omM7Sh-idGz2ahw19oAvpvSyKZVArG3o,48
-sigdetect-0.2.0.dist-info/top_level.txt,sha256=PKlfwUobkRC0viwiSXmhtw83G26FSNpimWYC1Uy00FY,10
-sigdetect-0.2.0.dist-info/RECORD,,
+sigdetect-0.3.1.dist-info/METADATA,sha256=whXGE4-9spAjlMcZz_owdsIiB4EobXL9_UOuAJeDVfA,12342
+sigdetect-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sigdetect-0.3.1.dist-info/entry_points.txt,sha256=iqtfKjBU44-omM7Sh-idGz2ahw19oAvpvSyKZVArG3o,48
+sigdetect-0.3.1.dist-info/top_level.txt,sha256=PKlfwUobkRC0viwiSXmhtw83G26FSNpimWYC1Uy00FY,10
+sigdetect-0.3.1.dist-info/RECORD,,