sigdetect 0.2.0__tar.gz → 0.3.1__tar.gz

{sigdetect-0.2.0 → sigdetect-0.3.1}/PKG-INFO

@@ -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 → sigdetect-0.3.1}/README.md

@@ -176,14 +176,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 → sigdetect-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sigdetect"
-version = "0.2.0"
+version = "0.3.1"
 description = "Signature detection and role attribution for PDFs"
 readme = "README.md"
 authors = [{ name = "BT Asmamaw", email = "basmamaw@angeiongroup.com" }]

{sigdetect-0.2.0 → sigdetect-0.3.1}/src/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-0.2.0 → sigdetect-0.3.1}/src/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 → sigdetect-0.3.1}/src/sigdetect.egg-info/PKG-INFO

@@ -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 → sigdetect-0.3.1}/tests/test_cropping.py

@@ -6,7 +6,7 @@ from pypdf.generic import ArrayObject, DictionaryObject, NameObject, NumberObjec
 
 from sigdetect.api import CropSignatureImages, DetectPdf
 from sigdetect.config import DetectConfiguration
-from sigdetect.cropping import crop_signatures
+from sigdetect.cropping import SignatureCrop, crop_signatures
 from sigdetect.detector.pypdf2_engine import PyPDF2Detector
 
 pytest.importorskip("fitz")
@@ -70,3 +70,85 @@ def test_crop_signature_images_accepts_dict(tmp_path: Path) -> None:
 
     assert paths
     assert result_dict["signatures"][0]["crop_path"] is not None
+
+
+def test_crop_signature_images_returns_bytes(tmp_path: Path) -> None:
+    pdf_path = tmp_path / "doc.pdf"
+    _pdf_with_signature(pdf_path)
+
+    result_dict = DetectPdf(pdf_path, engineName="pymupdf")
+    out_dir = tmp_path / "dict_byte_crops"
+    crops = CropSignatureImages(
+        pdf_path,
+        result_dict,
+        outputDirectory=out_dir,
+        returnBytes=True,
+    )
+
+    assert crops
+    assert isinstance(crops[0], SignatureCrop)
+    assert crops[0].image_bytes
+    assert result_dict["signatures"][0]["crop_path"] is not None
+
+
+def test_crop_signature_images_can_skip_disk(tmp_path: Path) -> None:
+    pdf_path = tmp_path / "doc.pdf"
+    _pdf_with_signature(pdf_path)
+
+    result_dict = DetectPdf(pdf_path, engineName="pymupdf")
+    out_dir = tmp_path / "dict_byte_crops_no_disk"
+    crops = CropSignatureImages(
+        pdf_path,
+        result_dict,
+        outputDirectory=out_dir,
+        returnBytes=True,
+        saveToDisk=False,
+    )
+
+    assert crops
+    first_crop = crops[0]
+    assert isinstance(first_crop, SignatureCrop)
+    assert first_crop.image_bytes
+    assert first_crop.saved_to_disk is False
+    assert not first_crop.path.exists()
+    assert result_dict["signatures"][0]["crop_path"] is None
+
+
+def test_crop_signatures_returns_bytes(tmp_path: Path) -> None:
+    pdf_path = tmp_path / "doc.pdf"
+    _pdf_with_signature(pdf_path)
+
+    cfg = DetectConfiguration(pdf_root=tmp_path, out_dir=tmp_path, engine="pypdf2")
+    result = PyPDF2Detector(cfg).Detect(pdf_path)
+
+    out_dir = tmp_path / "byte_crops"
+    crops = crop_signatures(
+        pdf_path,
+        result,
+        output_dir=out_dir,
+        dpi=120,
+        return_bytes=True,
+    )
+
+    assert crops
+    assert isinstance(crops[0], SignatureCrop)
+    assert crops[0].path.exists()
+    assert crops[0].image_bytes
+
+
+def test_crop_signatures_requires_save_or_bytes(tmp_path: Path) -> None:
+    pdf_path = tmp_path / "doc.pdf"
+    _pdf_with_signature(pdf_path)
+
+    cfg = DetectConfiguration(pdf_root=tmp_path, out_dir=tmp_path, engine="pypdf2")
+    result = PyPDF2Detector(cfg).Detect(pdf_path)
+
+    with pytest.raises(ValueError):
+        crop_signatures(
+            pdf_path,
+            result,
+            output_dir=tmp_path / "unused",
+            dpi=120,
+            save_files=False,
+            return_bytes=False,
+        )