scanlayer 1.0.0__py3-none-any.whl

scanlayer/utils/validators.py

@@ -0,0 +1,199 @@
+"""
+Input and runtime environment validation.
+
+Centralizes pre-checks to fail early with clear messages when prerequisites
+are missing. Each validator raises a specific ValidationError subclass.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from scanlayer import config
+from scanlayer.utils.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class ValidationError(Exception):
+    """Base for user-facing validation errors with actionable messages."""
+
+
+class InputFileError(ValidationError):
+    """The input file does not exist, is not readable, or has an unsupported format."""
+
+
+class OutputPathError(ValidationError):
+    """The output path is invalid (parent directory missing,
+    insufficient permissions, etc.)."""
+
+
+class TesseractEnvironmentError(ValidationError):
+    """Tesseract is missing, not found on PATH, or its tessdata is missing."""
+
+
+class DependencyError(ValidationError):
+    """A required Python dependency is not installed or broken."""
+
+
+SUPPORTED_IMAGE_EXTENSIONS = {
+    ".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp",
+    ".gif", ".webp", ".jp2", ".j2k",
+}
+
+_COMMON_LANG_FILES = {"eng.traineddata", "fra.traineddata", "osd.traineddata"}
+
+
+def validate_input_file(path: str) -> str:
+    """Check that the input file exists, is readable, and has a recognized extension.
+
+    Returns the resolved absolute path. Raises InputFileError on failure.
+    """
+    if not path or not isinstance(path, str):
+        raise InputFileError("No input path provided.")
+
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise InputFileError(
+            f"Input file does not exist: {path}\n"
+            f"Check the path and make sure you are in the correct directory."
+        )
+    if not p.is_file():
+        raise InputFileError(
+            f"The specified path is not a file: {path}"
+        )
+    if os.access(p, os.R_OK) is False:
+        raise InputFileError(
+            f"Input file is not readable (permissions): {path}"
+        )
+
+    ext = p.suffix.lower()
+    if ext not in SUPPORTED_IMAGE_EXTENSIONS:
+        log.warning(
+            f"Extension '{ext}' not in the supported list "
+            f"({', '.join(sorted(SUPPORTED_IMAGE_EXTENSIONS))}). "
+            f"Attempting anyway, Pillow will reject if the format is unknown."
+        )
+
+    if p.stat().st_size == 0:
+        raise InputFileError(f"Input file is empty: {path}")
+
+    return str(p.resolve())
+
+
+def validate_output_path(path: str, expected_ext: str = ".pdf") -> str:
+    """Check that the output path is valid (parent exists, is writable).
+
+    Returns the resolved absolute path. A mismatched extension only logs
+    a warning since the file is still written in the requested format.
+    Raises OutputPathError on failure.
+    """
+    if not path or not isinstance(path, str):
+        raise OutputPathError("No output path provided.")
+
+    p = Path(path).expanduser()
+    if p.exists() and p.is_dir():
+        raise OutputPathError(
+            f"The output path points to a directory, not a file: {path}"
+        )
+
+    parent = p.parent
+    if not parent.exists():
+        raise OutputPathError(
+            f"Parent directory of the output file does not exist: {parent}\n"
+            f"Create it first, or fix the output path."
+        )
+    if os.access(parent, os.W_OK) is False:
+        raise OutputPathError(
+            f"Output directory is not writable: {parent}"
+        )
+
+    ext = p.suffix.lower()
+    if ext != expected_ext.lower():
+        log.warning(
+            f"Output path does not have the {expected_ext} extension "
+            f"('{ext}'). The file will still be written in the "
+            f"requested format, but the extension is misleading."
+        )
+
+    return str(p.resolve())
+
+
+def validate_tesseract_environment() -> None:
+    """Check that Tesseract is installed and tessdata is available.
+
+    Raises TesseractEnvironmentError with an actionable message if not.
+    """
+    cmd = config.TESSERACT_CMD
+
+    if cmd not in ("tesseract",):
+        if not os.path.exists(cmd):
+            raise TesseractEnvironmentError(
+                f"Tesseract not found at the configured location: {cmd}\n"
+                f"Check config.DEV_TESSERACT_OVERRIDE, the "
+                f"TESSERACT_CMD environment variable, or scanlayer.configure().\n"
+                f"Install Tesseract via your package manager "
+                f"(apt install tesseract-ocr / brew install tesseract), "
+                f"or the Tesseract installer on Windows."
+            )
+        if not os.access(cmd, os.X_OK):
+            raise TesseractEnvironmentError(
+                f"Tesseract is not executable: {cmd} (permissions)"
+            )
+    else:
+        import shutil
+        resolved = shutil.which("tesseract")
+        if resolved is None:
+            raise TesseractEnvironmentError(
+                "Tesseract not found on the system PATH.\n"
+                "Install Tesseract via your package manager "
+                "(apt install tesseract-ocr / brew install tesseract / "
+                "or download the tesseract-ocr installer on Windows).\n"
+                "Or override the path via the TESSERACT_CMD=/path/to/tesseract "
+                "environment variable."
+            )
+
+    if config.TESSDATA_DIR:
+        td = Path(config.TESSDATA_DIR)
+        if not td.exists():
+            raise TesseractEnvironmentError(
+                f"Configured tessdata directory does not exist: {td}"
+            )
+        present = {f.name for f in td.glob("*.traineddata")}
+        missing_common = _COMMON_LANG_FILES - present
+        if missing_common:
+            log.warning(
+                f"Missing tessdata for: {', '.join(sorted(missing_common))}. "
+                f"OCR in those languages will fail."
+            )
+
+
+def validate_image_readable(path: str) -> None:
+    """Open the image with Pillow to verify it is not corrupted.
+
+    Raises InputFileError if Pillow cannot identify it.
+    """
+    try:
+        from PIL import Image
+        with Image.open(path) as img:
+            img.verify()  # does not load into memory, only checks the header
+    except Exception as exc:
+        raise InputFileError(
+            f"Unreadable or corrupted image: {path}\n"
+            f"Pillow could not identify it: {type(exc).__name__}: {exc}"
+        ) from exc
+
+
+def validate_all(
+    input_path: str, output_path: str, output_format: str = "pdf"
+) -> tuple[str, str]:
+    """Run all validations in order of fastest first.
+
+    Returns (input_abs, output_abs) if everything is OK.
+    """
+    input_abs = validate_input_file(input_path)
+    validate_tesseract_environment()
+    output_abs = validate_output_path(output_path, expected_ext=f".{output_format}")
+    validate_image_readable(input_abs)
+    return input_abs, output_abs

scanlayer-1.0.0.dist-info/METADATA

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: scanlayer
+Version: 1.0.0
+Summary: Image (scan/photo) to searchable PDF, or raw OCR export, via Tesseract.
+Requires-Python: >=3.9
+License-File: LICENSE.md
+Requires-Dist: pytesseract>=0.3.10
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: reportlab>=4.0.0
+Requires-Dist: opencv-python-headless>=4.8.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pdf2image>=1.17.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0; extra == "yaml"
+Dynamic: license-file

scanlayer-1.0.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+scanlayer/__init__.py,sha256=RVVGA5ggyXr5_dHpTZAlCk9tugT7ioqmUxW4we1Brr8,996
+scanlayer/__main__.py,sha256=7dtsL73buULWsVpixlyOrhw_ldPrxAkTzeh3FLDE5II,207
+scanlayer/config.py,sha256=HSndjcHm_teBEYgl9la0eFWuKwNrtUXWroDFh6QhlOw,7849
+scanlayer/main.py,sha256=07XiZ9ouXop6BQVj9CZCtH01YlzED35_N50SVsZ9jvQ,23158
+scanlayer/cli/__init__.py,sha256=fC3bR5kkWENgx31--7Y7tb3A8BGbXyg5D-z41aR9krY,205
+scanlayer/cli/dry_run.py,sha256=ueXZSrOLm2qV0G1n0k-zwG9qLggaAPhnjH685fPPNqQ,6860
+scanlayer/cli/parser.py,sha256=mUzE-qyliy9jGlEuUQ9HV8Pk-mWZWOQuRrvM2XEK07c,8570
+scanlayer/cli/run.py,sha256=BC8iZQ9aM8HPkXLU9VbHuC4-gFADrH6gTPPYi5EX2D4,7624
+scanlayer/fonts/DejaVuSans.ttf,sha256=rnt4VeEVpZZtixs_gPJUzMEX7Ib5ll4gLuKUBFODcoA,759720
+scanlayer/layout/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scanlayer/layout/columns.py,sha256=NuJHZ3AsbH7w2uXWriguS9VBNX94cAq9vXmOyd6mIuk,8596
+scanlayer/ocr/__init__.py,sha256=GI3op-X4or5sZ48XJc_17br0-V3BuryJ4VNkXjVG8Hk,181
+scanlayer/ocr/engine.py,sha256=FRkjsTK8cI0I8DWhWLViP8bTcQ-ZqdMvISkjx3_bHjc,11045
+scanlayer/ocr/export.py,sha256=u09trX5LYlf_x9Ly8lJXwYbpnd7M6hWNTaRePziNZbA,8941
+scanlayer/pdf/__init__.py,sha256=GCKBhmuxyriuas392LNtMVcdCM0_41wF3Nfi8dtXdjs,133
+scanlayer/pdf/builder.py,sha256=As7AHHonKgh8Mq6sbEzRXmRMNWfIyPR96B7EWdKJl08,10258
+scanlayer/pdf/fonts.py,sha256=Wh-_CypWvg4om3mif_cD1ml712fd8g6_547f5WLNKsc,3253
+scanlayer/preprocessing/__init__.py,sha256=byrSD5vjFvwEg-92nMJxA9CWVmPxpNfyJ0medhzR-QA,188
+scanlayer/preprocessing/enhance.py,sha256=877QZhnA2dnK93b3U0oCGsb6oHXAN27X1wB8FvTPFak,12640
+scanlayer/utils/__init__.py,sha256=V1q0cs2APJ7keK4Y4uwfFfBVqwJmqHJE7LzNThhKCMA,332
+scanlayer/utils/debug_image.py,sha256=z0dOuYwRmJedC7jvfbEJbGKA8NiHGpVsAO3WlhsyFV4,2564
+scanlayer/utils/errors.py,sha256=jr2OUiIevFSUJlWO90etav-GUOnP9O-3bXkHjPPSKnw,1827
+scanlayer/utils/logger.py,sha256=QIulvS3RjJ1fFkaNdlyaRM4wzVuZOg87hGnPsTmV4dA,3080
+scanlayer/utils/validators.py,sha256=oNHEgwrcY2X0MkUKYUWxtic4UZL6zypUv3hdjlTuBqY,6801
+scanlayer-1.0.0.dist-info/licenses/LICENSE.md,sha256=GnqaSHPX43GuJ4OQkCrW6zCf5eschtYCwHej5siK6w8,1079
+scanlayer-1.0.0.dist-info/METADATA,sha256=UWrnIa62RpJpnpGHlFsCOAFKT28vDlaGQVq9nd1-lec,538
+scanlayer-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+scanlayer-1.0.0.dist-info/entry_points.txt,sha256=1BhRpUFaKnTFgLWrRVAr8MAgpqmwH-8sz5kbmCkwf-s,49
+scanlayer-1.0.0.dist-info/top_level.txt,sha256=52X241TR07ERaeDJP76tmilaQcqfpDCpndN0nQJlGSs,10
+scanlayer-1.0.0.dist-info/RECORD,,

scanlayer-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scanlayer-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scanlayer = scanlayer.cli:main

scanlayer-1.0.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 scanlayer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scanlayer-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scanlayer