sigdetect 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

sigdetect/api.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
+from contextlib import contextmanager
 from pathlib import Path
-from typing import Any, Iterable, Iterator, Literal
+from typing import Any, Generator, Iterable, Iterator, Literal, overload
 
 from sigdetect.config import DetectConfiguration
-from sigdetect.detector import BuildDetector
+from sigdetect.cropping import SignatureCrop
+from sigdetect.detector import BuildDetector, Detector, FileResult, Signature
 
 EngineName = Literal["pypdf2", "pypdf", "pymupdf"]
 ProfileName = Literal["hipaa", "retainer"]
@@ -19,23 +21,44 @@ def DetectPdf(
     engineName: EngineName = "pypdf2",
     includePseudoSignatures: bool = True,
     recurseXObjects: bool = True,
+    detector: Detector | None = None,
 ) -> dict[str, Any]:
     """Detect signature evidence and assign roles for a single PDF."""
 
     resolvedPath = Path(pdfPath)
+    activeDetector = detector or get_detector(
+        pdfRoot=resolvedPath.parent,
+        profileName=profileName,
+        engineName=engineName,
+        includePseudoSignatures=includePseudoSignatures,
+        recurseXObjects=recurseXObjects,
+        outputDirectory=None,
+    )
+
+    result = activeDetector.Detect(resolvedPath)
+    return _ToPlainDictionary(result)
+
+
+def get_detector(
+    *,
+    pdfRoot: str | Path | None = None,
+    profileName: ProfileName = "hipaa",
+    engineName: EngineName = "pypdf2",
+    includePseudoSignatures: bool = True,
+    recurseXObjects: bool = True,
+    outputDirectory: str | Path | None = None,
+) -> Detector:
+    """Return a reusable detector instance configured with the supplied options."""
 
     configuration = DetectConfiguration(
-        PdfRoot=resolvedPath.parent,
-        OutputDirectory=None,
+        PdfRoot=Path(pdfRoot) if pdfRoot is not None else Path.cwd(),
+        OutputDirectory=Path(outputDirectory) if outputDirectory is not None else None,
         Engine=engineName,
         PseudoSignatures=includePseudoSignatures,
         RecurseXObjects=recurseXObjects,
         Profile=profileName,
     )
-
-    detector = BuildDetector(configuration)
-    result = detector.Detect(resolvedPath)
-    return _ToPlainDictionary(result)
+    return BuildDetector(configuration)
 
 
 def _ToPlainDictionary(candidate: Any) -> dict[str, Any]:
@@ -84,10 +107,17 @@ def _ToPlainValue(value: Any) -> Any:
 
 def DetectMany(
     pdfPaths: Iterable[str | Path],
+    *,
+    detector: Detector | None = None,
     **kwargs: Any,
 ) -> Iterator[dict[str, Any]]:
     """Yield :func:`DetectPdf` results for each path in ``pdfPaths``."""
 
+    if detector is not None:
+        for pdfPath in pdfPaths:
+            yield _DetectWithDetector(detector, pdfPath)
+        return
+
     for pdfPath in pdfPaths:
         yield DetectPdf(pdfPath, **kwargs)
 
@@ -96,19 +126,24 @@ def ScanDirectory(
     pdfRoot: str | Path,
     *,
     globPattern: str = "**/*.pdf",
+    detector: Detector | None = None,
     **kwargs: Any,
 ) -> Iterator[dict[str, Any]]:
     """Walk ``pdfRoot`` and yield detection output for every matching PDF."""
 
     rootDirectory = Path(pdfRoot)
-    iterator = (
-        rootDirectory.rglob(globPattern.replace("**/", "", 1))
-        if globPattern.startswith("**/")
-        else rootDirectory.glob(globPattern)
-    )
+    if globPattern == "**/*.pdf":
+        iterator = (path for path in rootDirectory.rglob("*") if path.is_file())
+    else:
+        iterator = (
+            rootDirectory.rglob(globPattern.replace("**/", "", 1))
+            if globPattern.startswith("**/")
+            else rootDirectory.glob(globPattern)
+        )
+
     for pdfPath in iterator:
         if pdfPath.is_file() and pdfPath.suffix.lower() == ".pdf":
-            yield DetectPdf(pdfPath, **kwargs)
+            yield DetectPdf(pdfPath, detector=detector, **kwargs)
 
 
 def ToCsvRow(result: dict[str, Any]) -> dict[str, Any]:
@@ -137,3 +172,116 @@ def Version() -> str:
         return resolveVersion("sigdetect")
     except Exception:
         return "0.0.0-dev"
+
+
+def _DetectWithDetector(detector: Detector, pdfPath: str | Path) -> dict[str, Any]:
+    """Helper that runs ``detector`` and returns the plain dictionary result."""
+
+    resolvedPath = Path(pdfPath)
+    return _ToPlainDictionary(detector.Detect(resolvedPath))
+
+
+@contextmanager
+def detector_context(**kwargs: Any) -> Generator[Detector, None, None]:
+    """Context manager wrapper around :func:`get_detector`."""
+
+    detector = get_detector(**kwargs)
+    try:
+        yield detector
+    finally:
+        pass
+
+
+@overload
+def CropSignatureImages(
+    pdfPath: str | Path,
+    fileResult: FileResult | dict[str, Any],
+    *,
+    outputDirectory: str | Path,
+    dpi: int = 200,
+    returnBytes: Literal[False] = False,
+) -> list[Path]: ...
+
+
+@overload
+def CropSignatureImages(
+    pdfPath: str | Path,
+    fileResult: FileResult | dict[str, Any],
+    *,
+    outputDirectory: str | Path,
+    dpi: int,
+    returnBytes: Literal[True],
+) -> list[SignatureCrop]: ...
+
+
+def CropSignatureImages(
+    pdfPath: str | Path,
+    fileResult: FileResult | dict[str, Any],
+    *,
+    outputDirectory: str | Path,
+    dpi: int = 200,
+    returnBytes: bool = False,
+) -> 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.
+    """
+
+    from sigdetect.cropping import crop_signatures
+
+    file_result_obj, original_dict = _CoerceFileResult(fileResult)
+    paths = crop_signatures(
+        pdf_path=Path(pdfPath),
+        file_result=file_result_obj,
+        output_dir=Path(outputDirectory),
+        dpi=dpi,
+        return_bytes=returnBytes,
+    )
+    if original_dict is not None:
+        original_dict.clear()
+        original_dict.update(file_result_obj.to_dict())
+    return paths
+
+
+def _CoerceFileResult(
+    candidate: FileResult | dict[str, Any]
+) -> tuple[FileResult, dict[str, Any] | None]:
+    if isinstance(candidate, FileResult):
+        return candidate, None
+    if not isinstance(candidate, dict):
+        raise TypeError("fileResult must be FileResult or dict")
+
+    signatures: list[Signature] = []
+    for entry in candidate.get("signatures") or []:
+        bbox = entry.get("bounding_box")
+        signatures.append(
+            Signature(
+                Page=entry.get("page"),
+                FieldName=str(entry.get("field_name") or ""),
+                Role=str(entry.get("role") or "unknown"),
+                Score=int(entry.get("score") or 0),
+                Scores=dict(entry.get("scores") or {}),
+                Evidence=list(entry.get("evidence") or []),
+                Hint=str(entry.get("hint") or ""),
+                RenderType=str(entry.get("render_type") or "unknown"),
+                BoundingBox=tuple(bbox) if bbox else None,
+                CropPath=entry.get("crop_path"),
+            )
+        )
+
+    file_result = FileResult(
+        File=str(candidate.get("file") or ""),
+        SizeKilobytes=candidate.get("size_kb"),
+        PageCount=int(candidate.get("pages") or 0),
+        ElectronicSignatureFound=bool(candidate.get("esign_found")),
+        ScannedPdf=candidate.get("scanned_pdf"),
+        MixedContent=candidate.get("mixed"),
+        SignatureCount=int(candidate.get("sig_count") or len(signatures)),
+        SignaturePages=str(candidate.get("sig_pages") or ""),
+        Roles=str(candidate.get("roles") or "unknown"),
+        Hints=str(candidate.get("hints") or ""),
+        Signatures=signatures,
+    )
+    return file_result, candidate

sigdetect/cli.py

@@ -3,14 +3,16 @@
 from __future__ import annotations
 
 import json
+from collections.abc import Iterator
 from dataclasses import asdict, is_dataclass
 from pathlib import Path
 
 import typer
 
 from . import __version__
-from .config import LoadConfiguration
-from .detector import BuildDetector
+from .config import FinalizeConfiguration, LoadConfiguration
+from .cropping import SignatureCroppingUnavailable, crop_signatures
+from .detector import BuildDetector, FileResult
 from .eda import RunExploratoryAnalysis
 from .logging_setup import ConfigureLogging
 
@@ -31,18 +33,65 @@ def _JsonSerializer(candidate):
     return str(candidate)
 
 
+def _EnumeratePdfs(pdfRoot: Path, recursive: bool) -> Iterator[Path]:
+    """Yield PDF files under ``pdfRoot`` honoring the recursion flag."""
+
+    iterator = pdfRoot.rglob("*") if recursive else pdfRoot.glob("*")
+    for path in iterator:
+        if path.is_file() and path.suffix.lower() == ".pdf":
+            yield path
+
+
 @CliApplication.command(name="detect")
 def Detect(
     configurationPath: Path | None = typer.Option(
         None, "--config", "-c", help="Path to YAML config"
     ),
     profileOverride: str | None = typer.Option(None, "--profile", "-p", help="hipaa or retainer"),
+    recursive: bool = typer.Option(
+        True,
+        "--recursive/--no-recursive",
+        help="Recurse into subdirectories when gathering PDFs",
+    ),
+    cropSignatures: bool | None = typer.Option(
+        None,
+        "--crop-signatures/--no-crop-signatures",
+        help="Crop detected signature regions to PNG files (requires PyMuPDF)",
+        show_default=False,
+    ),
+    cropDirectory: Path | None = typer.Option(
+        None,
+        "--crop-dir",
+        help="Directory for signature PNG crops (defaults to out_dir/signature_crops)",
+    ),
+    cropDpi: int | None = typer.Option(
+        None,
+        "--crop-dpi",
+        min=72,
+        max=600,
+        help="Rendering DPI for signature crops",
+        show_default=False,
+    ),
 ) -> None:
     """Run detection for the configured directory and emit ``results.json``."""
 
     configuration = LoadConfiguration(configurationPath)
-    if profileOverride in {"hipaa", "retainer"}:
-        configuration = configuration.model_copy(update={"Profile": profileOverride})
+    if profileOverride is not None:
+        normalized_profile = profileOverride.lower()
+        if normalized_profile not in {"hipaa", "retainer"}:
+            raise typer.BadParameter("Profile must be 'hipaa' or 'retainer'.")
+        configuration = configuration.model_copy(update={"Profile": normalized_profile})
+
+    overrides: dict[str, object] = {}
+    if cropSignatures is not None:
+        overrides["CropSignatures"] = cropSignatures
+    if cropDirectory is not None:
+        overrides["CropOutputDirectory"] = cropDirectory
+    if cropDpi is not None:
+        overrides["CropImageDpi"] = cropDpi
+    if overrides:
+        configuration = configuration.model_copy(update=overrides)
+        configuration = FinalizeConfiguration(configuration)
 
     try:
         detector = BuildDetector(configuration)
@@ -54,26 +103,111 @@ def Detect(
         typer.echo(str(exc), err=True)
         raise typer.Exit(code=2) from exc
 
-    pdfFiles = list(configuration.PdfRoot.glob("*.pdf"))
-    if not pdfFiles:
-        raise SystemExit(f"No PDFs found in {configuration.PdfRoot}")
-
-    results = [detector.Detect(pdfPath) for pdfPath in pdfFiles]
+    pdfIterator = _EnumeratePdfs(configuration.PdfRoot, recursive)
+    try:
+        firstPdf = next(pdfIterator)
+    except StopIteration:
+        raise SystemExit(f"No PDFs found in {configuration.PdfRoot}") from None
+
+    results_buffer: list[FileResult] | None = [] if configuration.OutputDirectory is None else None
+    json_handle = None
+    json_path: Path | None = None
+    wrote_first = False
+
+    if configuration.OutputDirectory is not None:
+        outputDirectory = configuration.OutputDirectory
+        outputDirectory.mkdir(parents=True, exist_ok=True)
+        json_path = outputDirectory / "results.json"
+        json_handle = open(json_path, "w", encoding="utf-8")
+        json_handle.write("[")
+
+    crop_dir = configuration.CropOutputDirectory
+    cropping_enabled = configuration.CropSignatures
+    cropping_available = True
+    cropping_attempted = False
+    if configuration.CropSignatures and crop_dir is None:
+        Logger.warning(
+            "CropSignatures enabled without an output directory",
+            extra={"pdf_root": str(configuration.PdfRoot)},
+        )
+        cropping_enabled = False
+
+    total_bboxes = 0
+
+    def _append_result(file_result: FileResult, source_pdf: Path) -> None:
+        nonlocal wrote_first, json_handle, total_bboxes, cropping_available, cropping_attempted
+
+        if cropping_enabled and cropping_available and crop_dir is not None:
+            try:
+                crop_signatures(
+                    pdf_path=source_pdf,
+                    file_result=file_result,
+                    output_dir=crop_dir,
+                    dpi=configuration.CropImageDpi,
+                    logger=Logger,
+                )
+                cropping_attempted = True
+            except SignatureCroppingUnavailable as exc:
+                cropping_available = False
+                Logger.warning("Signature cropping unavailable", extra={"error": str(exc)})
+                typer.echo(str(exc), err=True)
+            except Exception as exc:  # pragma: no cover - defensive
+                Logger.warning(
+                    "Unexpected error while cropping signatures",
+                    extra={"error": str(exc)},
+                )
+
+        total_bboxes += sum(1 for sig in file_result.Signatures if sig.BoundingBox)
+
+        if results_buffer is not None:
+            results_buffer.append(file_result)
+            return
+
+        if json_handle is None:
+            return
+
+        serialized = json.dumps(
+            file_result,
+            indent=2,
+            ensure_ascii=False,
+            default=_JsonSerializer,
+        )
+        indented = "\n".join(f"  {line}" for line in serialized.splitlines())
+        if wrote_first:
+            json_handle.write(",\n")
+        else:
+            json_handle.write("\n")
+        json_handle.write(indented)
+        wrote_first = True
+
+    def _process(pdf_path: Path) -> None:
+        file_result = detector.Detect(pdf_path)
+        _append_result(file_result, pdf_path)
 
-    # Allow configuration to suppress file output entirely (out_dir: none / SIGDETECT_OUT_DIR=none)
-    if configuration.OutputDirectory is None:
-        payload = json.dumps(results, indent=2, ensure_ascii=False, default=_JsonSerializer)
+    try:
+        _process(firstPdf)
+        for pdf_path in pdfIterator:
+            _process(pdf_path)
+    finally:
+        if json_handle is not None:
+            closing = "\n]\n" if wrote_first else "]\n"
+            json_handle.write(closing)
+            json_handle.close()
+
+    if json_handle is not None:
+        typer.echo(f"Wrote {json_path}")
+    else:
+        payload = json.dumps(
+            results_buffer or [], indent=2, ensure_ascii=False, default=_JsonSerializer
+        )
         typer.echo(payload)
         typer.echo("Detection completed with output disabled (out_dir=none)")
-        return
-
-    outputDirectory = configuration.OutputDirectory
-    outputDirectory.mkdir(parents=True, exist_ok=True)
 
-    with open(outputDirectory / "results.json", "w", encoding="utf-8") as handle:
-        json.dump(results, handle, indent=2, ensure_ascii=False, default=_JsonSerializer)
-
-    typer.echo(f"Wrote {outputDirectory / 'results.json'}")
+    if cropping_enabled and cropping_available and cropping_attempted and total_bboxes == 0:
+        Logger.warning(
+            "No signature bounding boxes detected; try --engine pymupdf for crop-ready output",
+            extra={"engine": configuration.Engine},
+        )
 
 
 @CliApplication.command(name="eda")

sigdetect/config.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import os
+from contextlib import suppress
 from pathlib import Path
 from typing import Literal
 
@@ -26,11 +27,13 @@ class DetectConfiguration(BaseModel):
     OutputDirectory: Path | None = Field(default=Path("out"), alias="out_dir")
     Engine: EngineName = Field(default="pypdf2", alias="engine")
     Profile: ProfileName = Field(default="hipaa", alias="profile")
-    MaxWorkers: int = Field(default=8, alias="max_workers", ge=1, le=64)
     PseudoSignatures: bool = Field(default=True, alias="pseudo_signatures")
     RecurseXObjects: bool = Field(default=True, alias="recurse_xobjects")
+    CropSignatures: bool = Field(default=False, alias="crop_signatures")
+    CropOutputDirectory: Path | None = Field(default=None, alias="crop_output_dir")
+    CropImageDpi: int = Field(default=200, alias="crop_image_dpi", ge=72, le=600)
 
-    @field_validator("PdfRoot", "OutputDirectory", mode="before")
+    @field_validator("PdfRoot", "OutputDirectory", "CropOutputDirectory", mode="before")
     @classmethod
     def _CoercePath(cls, value: str | Path | None) -> Path | None:
         """Allow configuration values to be provided as ``str`` or ``Path``.
@@ -42,8 +45,8 @@ class DetectConfiguration(BaseModel):
         if value is None:
             return None
         if isinstance(value, Path):
-            return value
-        return Path(value)
+            return value.expanduser()
+        return Path(value).expanduser()
 
     # Expose legacy snake_case property names for gradual migration
     @property
@@ -62,10 +65,6 @@ class DetectConfiguration(BaseModel):
     def profile(self) -> ProfileName:  # pragma: no cover - simple passthrough
         return self.Profile
 
-    @property
-    def max_workers(self) -> int:  # pragma: no cover - simple passthrough
-        return self.MaxWorkers
-
     @property
     def pseudo_signatures(self) -> bool:  # pragma: no cover - simple passthrough
         return self.PseudoSignatures
@@ -74,6 +73,18 @@ class DetectConfiguration(BaseModel):
     def recurse_xobjects(self) -> bool:  # pragma: no cover - simple passthrough
         return self.RecurseXObjects
 
+    @property
+    def crop_signatures(self) -> bool:  # pragma: no cover - simple passthrough
+        return self.CropSignatures
+
+    @property
+    def crop_output_dir(self) -> Path | None:  # pragma: no cover - simple passthrough
+        return self.CropOutputDirectory
+
+    @property
+    def crop_image_dpi(self) -> int:  # pragma: no cover - simple passthrough
+        return self.CropImageDpi
+
 
 def LoadConfiguration(path: Path | None) -> DetectConfiguration:
     """Load configuration from ``path`` while applying environment overrides.
@@ -94,6 +105,9 @@ def LoadConfiguration(path: Path | None) -> DetectConfiguration:
     env_pdf_root = os.getenv("SIGDETECT_PDF_ROOT")
     env_out_dir = os.getenv("SIGDETECT_OUT_DIR")
     env_profile = os.getenv("SIGDETECT_PROFILE")
+    env_crop = os.getenv("SIGDETECT_CROP_SIGNATURES")
+    env_crop_dir = os.getenv("SIGDETECT_CROP_DIR")
+    env_crop_dpi = os.getenv("SIGDETECT_CROP_DPI")
 
     raw_data: dict[str, object] = {}
     if path and Path(path).exists():
@@ -108,10 +122,36 @@ def LoadConfiguration(path: Path | None) -> DetectConfiguration:
         raw_data["out_dir"] = None if env_out_dir.lower() == "none" else env_out_dir
     if env_profile in {"hipaa", "retainer"}:
         raw_data["profile"] = env_profile
+    if env_crop is not None:
+        lowered = env_crop.lower()
+        if lowered in {"1", "true", "yes", "on"}:
+            raw_data["crop_signatures"] = True
+        elif lowered in {"0", "false", "no", "off"}:
+            raw_data["crop_signatures"] = False
+    if env_crop_dir:
+        raw_data["crop_output_dir"] = env_crop_dir
+    if env_crop_dpi:
+        with suppress(ValueError):
+            raw_data["crop_image_dpi"] = int(env_crop_dpi)
 
     configuration = DetectConfiguration(**raw_data)
+    return FinalizeConfiguration(configuration)
+
+
+def FinalizeConfiguration(configuration: DetectConfiguration) -> DetectConfiguration:
+    """Ensure derived directories exist and defaults are populated."""
+
+    updates: dict[str, object] = {}
 
     if configuration.OutputDirectory is not None:
         configuration.OutputDirectory.mkdir(parents=True, exist_ok=True)
 
-    return configuration
+    if configuration.CropSignatures:
+        crop_dir = configuration.CropOutputDirectory
+        if crop_dir is None:
+            base_dir = configuration.OutputDirectory or configuration.PdfRoot
+            crop_dir = base_dir / "signature_crops"
+        crop_dir.mkdir(parents=True, exist_ok=True)
+        updates["CropOutputDirectory"] = crop_dir
+
+    return configuration if not updates else configuration.model_copy(update=updates)