scanlayer 1.0.0__py3-none-any.whl

scanlayer/__init__.py

@@ -0,0 +1,32 @@
+"""
+scanlayer: turn a scanned or photographed document into a searchable PDF,
+or export the raw OCR result as text, JSON, TSV, or hOCR.
+
+Usage:
+
+    import scanlayer
+
+    result = scanlayer.convert("invoice.jpg", "invoice.pdf")
+    print(result.words_count, result.mean_confidence)
+
+For batch processing, use convert_batch() which handles mixed extensions
+and never raises for a single bad file.
+
+Tesseract is located automatically. Use configure() to override:
+
+    scanlayer.configure(tesseract_cmd="/path/to/tesseract", lang="eng")
+
+See scanlayer.config.configure for the full list of options.
+"""
+
+from scanlayer.config import configure, configure_from_file, get_settings, load_config_file
+from scanlayer.main import BatchResult, ConversionResult, convert, convert_batch, convert_merge
+
+__all__ = [
+    "configure", "configure_from_file", "load_config_file", "get_settings",
+    "convert", "ConversionResult",
+    "convert_batch", "BatchResult",
+    "convert_merge",
+]
+
+__version__ = "1.0.0"

scanlayer/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for `python -m scanlayer`.
+
+Avoids double-importing main.py since __init__.py already imports it.
+"""
+
+from scanlayer.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scanlayer/cli/__init__.py

@@ -0,0 +1,10 @@
+"""
+CLI entry point for scanlayer.
+
+Exit codes: 0=success, 1=user error, 2=env error, 3=unexpected,
+4=processing error, 5=partial batch failure.
+"""
+
+from scanlayer.cli.run import main
+
+__all__ = ["main"]

scanlayer/cli/dry_run.py

@@ -0,0 +1,191 @@
+"""
+Exit codes and --dry-run validation logic for the scanlayer CLI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from typing import Optional
+
+from scanlayer.main import _default_output_path
+from scanlayer.utils.errors import BlankPageDetectedError, PipelineError
+from scanlayer.utils.logger import log_error
+from scanlayer.utils.validators import (
+    DependencyError,
+    InputFileError,
+    OutputPathError,
+    TesseractEnvironmentError,
+    ValidationError,
+    validate_image_readable,
+    validate_input_file,
+    validate_output_path,
+    validate_tesseract_environment,
+)
+
+EXIT_OK = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+EXIT_UNEXPECTED_ERROR = 3
+EXIT_PROCESSING_ERROR = 4
+EXIT_PARTIAL_BATCH = 5
+
+def _exit_code_for(exc: Exception) -> int:
+    if isinstance(exc, (InputFileError, OutputPathError)):
+        return EXIT_USER_ERROR
+    if isinstance(exc, (TesseractEnvironmentError, DependencyError)):
+        return EXIT_ENV_ERROR
+    if isinstance(exc, ValidationError):
+        return EXIT_USER_ERROR
+    if isinstance(exc, BlankPageDetectedError):
+        return EXIT_USER_ERROR  # not a bug/env issue, user needs to pass --force
+    if isinstance(exc, PipelineError):
+        return EXIT_PROCESSING_ERROR
+    return EXIT_UNEXPECTED_ERROR
+
+
+def _dry_run_resolve_output_path(
+    output_arg: str, input_path: str, is_batch: bool, output_format: str = "pdf"
+) -> "tuple[str, Optional[str]]":
+    """Like _resolve_output_path(), but never touches the filesystem.
+
+    _resolve_output_path() calls os.makedirs() as a side effect for
+    folder-style -o, which --dry-run must not do. Returns
+    (resolved_output_path, folder_or_None) – folder is set when this
+    is the auto-created-folder case, so the caller can validate it
+    without creating it.
+    """
+    if output_arg is None:
+        return _default_output_path(input_path, output_format), None
+    is_folder = is_batch or output_arg.endswith(("/", "\\")) or os.path.isdir(output_arg)
+    if is_folder:
+        stem = os.path.splitext(os.path.basename(input_path))[0]
+        return os.path.join(output_arg, f"{stem}.{output_format}"), output_arg
+    return output_arg, None
+
+
+def _nearest_existing_dir(path: str) -> str:
+    """Walk up from `path` to the nearest ancestor that already
+    exists. Used to check whether os.makedirs(path) would succeed
+    without actually calling it.
+    """
+    path = os.path.abspath(path)
+    while not os.path.isdir(path):
+        parent = os.path.dirname(path)
+        if parent == path:
+            return path
+        path = parent
+    return path
+
+
+def _check_output_folder_creatable(folder: str) -> None:
+    """Dry-run equivalent of the os.makedirs(exist_ok=True) a real
+    batch run does for folder-style -o: confirms the folder (or its
+    nearest existing ancestor, standing in for what makedirs would
+    need to write into) is writable, without creating anything.
+    """
+    if os.path.exists(folder):
+        if not os.path.isdir(folder):
+            raise OutputPathError(
+                f"The output path points to a file, not a directory: {folder}"
+            )
+        target = folder
+    else:
+        target = _nearest_existing_dir(folder)
+    if os.access(target, os.W_OK) is False:
+        raise OutputPathError(f"Output directory is not writable: {target}")
+
+
+def _dry_run_validate_one(
+    input_path: str, output_path: str, folder: "Optional[str]", output_format: str
+) -> None:
+    """Same checks as validate_all(), fastest first, but uses the
+    dry-run folder check instead of validate_output_path() when the
+    output path is an auto-created batch folder that may not exist
+    yet (validate_output_path() would otherwise reject it for a
+    reason a real run would just fix by creating the folder).
+    """
+    input_abs = validate_input_file(input_path)
+    validate_tesseract_environment()
+    if folder is not None:
+        _check_output_folder_creatable(folder)
+    else:
+        validate_output_path(output_path, expected_ext=f".{output_format}")
+    validate_image_readable(input_abs)
+
+
+def _run_dry_run(
+    expanded_inputs: list[str], args: argparse.Namespace, log
+) -> int:
+    """Validate a batch (files exist/readable, Tesseract reachable,
+    output paths writable) without running OCR or writing anything.
+
+    Non-merge: mirrors the exit-code behavior of the real conversion
+    loop in main() – a single input's failure returns that failure's
+    own exit code immediately, multi-input runs collect every
+    failure and return EXIT_PARTIAL_BATCH if any file failed.
+
+    --merge: mirrors convert_merge(), which combines all pages into
+    ONE output and aborts on the first bad page rather than
+    collecting per-file failures, so dry-run does the same (fail
+    fast on the first bad page, no EXIT_PARTIAL_BATCH here).
+    """
+    is_batch = len(expanded_inputs) > 1
+
+    if args.merge:
+        # main() already rejects args.merge with args.output is None
+        # before _run_dry_run is reached.
+        try:
+            validate_output_path(args.output, expected_ext=".pdf")
+        except ValidationError as exc:
+            log_error(log, f"'--output': {exc}")
+            return _exit_code_for(exc)
+        try:
+            validate_tesseract_environment()
+        except ValidationError as exc:
+            log_error(log, f"'--merge': {exc}")
+            return _exit_code_for(exc)
+
+        for input_path in expanded_inputs:
+            try:
+                input_abs = validate_input_file(input_path)
+                validate_image_readable(input_abs)
+            except ValidationError as exc:
+                log_error(log, f"'{input_path}': {exc}")
+                return _exit_code_for(exc)
+
+        log.info(
+            f"dry-run: {len(expanded_inputs)} file(s) OK for --merge "
+            f"into {args.output}, no output written."
+        )
+        return EXIT_OK
+
+    failures: list[tuple[str, str]] = []
+    last_exit_code = EXIT_OK
+
+    for input_path in expanded_inputs:
+        output_path, folder = _dry_run_resolve_output_path(
+            args.output, input_path, is_batch, args.format
+        )
+        try:
+            _dry_run_validate_one(input_path, output_path, folder, args.format)
+        except Exception as exc:
+            code = _exit_code_for(exc)
+            log_error(log, f"'{input_path}': {exc}")
+            failures.append((input_path, str(exc)))
+            last_exit_code = code
+            if not is_batch:
+                return last_exit_code
+
+    if failures:
+        if is_batch:
+            log_error(
+                log,
+                f"dry-run: {len(failures)}/{len(expanded_inputs)} "
+                f"file(s) failed validation.",
+            )
+            return EXIT_PARTIAL_BATCH
+        return last_exit_code
+
+    log.info(f"dry-run: {len(expanded_inputs)} file(s) OK, no output written.")
+    return EXIT_OK

scanlayer/cli/parser.py

@@ -0,0 +1,199 @@
+"""
+CLI argument parser for scanlayer.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from scanlayer import config
+
+
+class _ScanlayerHelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """Wider help column and wrapping so long option descriptions stay
+    readable instead of collapsing into a single dense block."""
+
+    def __init__(self, prog):
+        super().__init__(prog, max_help_position=28, width=100)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="scanlayer",
+        description="Convert a scanned image into a searchable PDF, or export the raw OCR result.",
+        formatter_class=_ScanlayerHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  scanlayer invoice.jpg -o invoice.pdf\n"
+            "  scanlayer invoice.jpg -o invoice.pdf --lang fra --dpi 300\n"
+            "  scanlayer invoice.jpg -o invoice.pdf --verbose\n"
+            "  scanlayer invoice.jpg -o invoice.pdf --jpeg-quality 90\n"
+            "  scanlayer *.jpg -o ./converted/   (batch: -o is a folder)\n"
+            "  scanlayer invoice.jpg -o invoice.pdf --orientation none\n"
+            "  scanlayer invoice.jpg -o invoice.pdf --orientation 10\n"
+            "  scanlayer invoice.jpg -o invoice.json --format json\n"
+            "  scanlayer invoice.jpg -o invoice.pdf --debug-image\n"
+            "  scanlayer invoice.jpg --debug-image   (no -o: writes "
+            "invoice.pdf + invoice_debug.png next to the input)\n"
+            "  scanlayer invoice.jpg -o invoice.pdf --font ./MyFont.ttf\n"
+            "  scanlayer *.jpg -o ./converted/ --dry-run   (validate, no OCR)\n"
+            "\n"
+            "Exit codes:\n"
+            "  0 = success\n"
+            "  1 = user error (file not found, invalid format, blank page "
+            "without --force...)\n"
+            "  2 = environment error (Tesseract missing...)\n"
+            "  3 = unexpected error (bug)\n"
+            "  4 = processing error (OCR/PDF stage failed for a real reason)\n"
+            "  5 = partial batch failure (multiple inputs, some failed)\n"
+        ),
+    )
+    parser.add_argument(
+        "input", nargs="+",
+        help="Path(s) to the source image(s) (jpg, png, tiff...). "
+             "Give several and point -o at a folder to batch-convert.",
+    )
+
+    io_group = parser.add_argument_group("input / output")
+    io_group.add_argument(
+        "-o", "--output", required=False, default=None,
+        help="Output PDF path (single input) or folder (multiple "
+             "inputs). If omitted, each output is written next to its "
+             "own input, same directory/stem, extension from --format. "
+             "Required when --merge is used.",
+    )
+    io_group.add_argument(
+        "--format", choices=["pdf", "txt", "json", "tsv", "hocr"], default="pdf",
+        help="Output format. 'pdf' (default) builds a searchable PDF. "
+             "'txt', 'json', 'tsv', 'hocr' export the raw OCR result "
+             "instead, no PDF is built. See the README for each "
+             "format's schema.",
+    )
+    io_group.add_argument(
+        "--merge", action="store_true",
+        help="Combine all inputs into ONE multi-page PDF instead of "
+             "one output per input. Works with multiple image "
+             "arguments (page order = argument order) or a single "
+             "multi-page PDF input. Only with --format pdf. -o must "
+             "be a file path, not a folder.",
+    )
+    io_group.add_argument(
+        "--config", default=None,
+        help="Path to a .yaml/.yml/.json config profile applied via "
+             "configure() before any other option (CLI flags still "
+             "override it). Keys match configure()'s kwargs, e.g. "
+             '{"tesseract_cmd": "/usr/bin/tesseract", "lang": "eng"}. '
+             "See scanlayer.config.configure for the full key list.",
+    )
+
+    ocr_group = parser.add_argument_group("OCR options")
+    ocr_group.add_argument(
+        "--lang", default=None,
+        help="Tesseract language(s), e.g. fra, eng, fra+eng "
+             "(default: fra+eng)",
+    )
+    ocr_group.add_argument(
+        "--dpi", type=int, default=None,
+        help="DPI to use if not detectable in the image",
+    )
+    ocr_group.add_argument(
+        "--psm", type=int, default=None, metavar="N",
+        help="Force a single page segmentation mode instead of trying "
+             "TESSERACT_PSM_CANDIDATES (default [3, 4, 6, 11]) and "
+             "keeping the highest mean confidence. Runs exactly one "
+             "OCR pass, no auto-selection. Common values: 3 (fully "
+             "automatic), 4 (single column), 6 (single uniform block, "
+             "e.g. receipts), 7 (single line), 11 (sparse/scattered "
+             "text, e.g. order forms). 0 and 2 are rejected, they "
+             "produce no OCR text.",
+    )
+    ocr_group.add_argument(
+        "--orientation", default=None,
+        help="Orientation correction mode. Omit for automatic "
+             "detection (EXIF + OSD + deskew, the default). 'none' "
+             "disables correction and uses the image as loaded. Or "
+             "give a precise clockwise angle in degrees (e.g. '10' "
+             "or '-3.5') to skip auto-detection.",
+    )
+    ocr_group.add_argument(
+        "--no-column-detection", action="store_true",
+        help="Disable multi-column reading-order detection for this "
+             "run, e.g. if it misfires on a specific document. "
+             "Equivalent to configure(multi_column_detection=False).",
+    )
+    ocr_group.add_argument(
+        "--min-confidence", type=int, default=None,
+        help="Confidence threshold (0-100) below which a word is "
+             f"dropped (default: {config.MIN_WORD_CONFIDENCE})",
+    )
+    ocr_group.add_argument(
+        "--whitelist", default=None,
+        help="Allowed characters for OCR, e.g. "
+             "'0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'",
+    )
+    ocr_group.add_argument(
+        "--blacklist", default=None,
+        help="Forbidden characters for OCR, e.g. '|`~'",
+    )
+    ocr_group.add_argument(
+        "--font", default=None,
+        help="TTF font to embed in the invisible text layer, "
+             "overriding the automatic pick (CJK CID font / bundled "
+             "DejaVu Sans / Helvetica fallback based on --lang). "
+             "Useful for scripts the auto-pick misses (Arabic, "
+             "Hebrew, Thai, Devanagari...).",
+    )
+
+    pdf_group = parser.add_argument_group("PDF output")
+    pdf_group.add_argument(
+        "--jpeg-quality", type=int, default=None,
+        help=f"JPEG quality for the background (default: {config.PDF_JPEG_QUALITY})",
+    )
+    pdf_group.add_argument(
+        "--title", default=None,
+        help="Title of the PDF document (metadata)",
+    )
+    pdf_group.add_argument(
+        "--author", default=None,
+        help="Author of the PDF document (metadata)",
+    )
+    pdf_group.add_argument(
+        "--subject", default=None,
+        help="Subject of the PDF document (metadata)",
+    )
+    pdf_group.add_argument(
+        "--force", action="store_true",
+        help="Generate the PDF even if the source image looks "
+             "blank/near-uniform (background image only, no text "
+             "layer, no OCR run). Without this, a likely-blank page "
+             "raises an error instead of silently producing an "
+             "empty PDF.",
+    )
+
+    diag_group = parser.add_argument_group("diagnostics")
+    diag_group.add_argument(
+        "--debug-image", action="store_true",
+        help="Also save a '<output-stem>_debug.png' next to the "
+             "output, showing detected word boxes color-coded by "
+             "confidence, per-word confidence scores, and run "
+             "metadata. Works with any --format.",
+    )
+    diag_group.add_argument(
+        "--dry-run", action="store_true",
+        help="Validate the batch without running OCR or writing any "
+             "output: checks inputs exist and are readable, Tesseract "
+             "is reachable, and output paths are writable. Exits with "
+             "the same codes as a normal run, so scripts can fail "
+             "fast before paying for OCR. Combine with --merge to "
+             "validate a merge run instead.",
+    )
+    diag_group.add_argument(
+        "-v", "--verbose", action="store_true",
+        help="Enable verbose logging (DEBUG level)",
+    )
+    diag_group.add_argument(
+        "-q", "--quiet", action="store_true",
+        help="Suppress all logs except errors (ERROR level)",
+    )
+
+    return parser

scanlayer/cli/run.py

@@ -0,0 +1,217 @@
+"""
+CLI run orchestration for scanlayer: argument handling, config wiring,
+and the main conversion loop. Maps exceptions to exit codes.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import sys
+import tempfile
+
+from scanlayer import config
+from scanlayer.cli.dry_run import (
+    EXIT_OK,
+    EXIT_PARTIAL_BATCH,
+    EXIT_UNEXPECTED_ERROR,
+    EXIT_USER_ERROR,
+    _exit_code_for,
+    _run_dry_run,
+)
+from scanlayer.cli.parser import _build_parser
+from scanlayer.main import _expand_pdf_input, _resolve_output_path, convert, convert_merge
+from scanlayer.utils.logger import get_logger, log_error
+
+
+def main(argv: list[str] = None) -> int:
+    """CLI entry point. Returns a standardized exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.verbose:
+        os.environ["LOG_LEVEL"] = "DEBUG"
+    elif args.quiet:
+        os.environ["LOG_LEVEL"] = "ERROR"
+
+    log = get_logger("main")
+
+    if args.config:
+        try:
+            file_settings = config.configure_from_file(args.config)
+            log.info(f"Applied config file: {args.config} ({sorted(file_settings)})")
+        except (FileNotFoundError, ValueError) as exc:
+            log_error(log, f"--config: {exc}")
+            return EXIT_USER_ERROR
+
+    if args.no_column_detection:
+        config.configure(multi_column_detection=False)
+
+    if args.psm is not None:
+        if args.psm in (0, 2):
+            log_error(
+                log,
+                f"--psm {args.psm}: PSM 0 and 2 only run orientation/script "
+                "detection, they don't produce OCR text, so no words would "
+                "be extracted. Pick a PSM that actually reads text, e.g. "
+                "3, 4, 6, 7, or 11 (see --help for --psm).",
+            )
+            return EXIT_USER_ERROR
+        if not 0 <= args.psm <= 13:
+            log_error(
+                log,
+                f"--psm must be a Tesseract page segmentation mode, 0-13. "
+                f"Got {args.psm}.",
+            )
+            return EXIT_USER_ERROR
+        config.configure(psm_candidates=[args.psm])
+
+    if args.font:
+        config.configure(font_path=args.font)
+
+    if args.min_confidence is not None:
+        if not 0 <= args.min_confidence <= 100:
+            log_error(log, "--min-confidence must be between 0 and 100.")
+            return EXIT_USER_ERROR
+        config.MIN_WORD_CONFIDENCE = args.min_confidence
+
+    orientation_value: "str | float | None" = None
+    if args.orientation is not None:
+        if args.orientation.strip().lower() == "none":
+            orientation_value = "none"
+        else:
+            try:
+                orientation_value = float(args.orientation)
+            except ValueError:
+                log_error(
+                    log,
+                    f"--orientation must be 'none' or a numeric angle in "
+                    f"degrees, got: '{args.orientation}'."
+                )
+                return EXIT_USER_ERROR
+
+    pdf_metadata = {}
+    if args.title:
+        pdf_metadata["title"] = args.title
+    if args.author:
+        pdf_metadata["author"] = args.author
+    if args.subject:
+        pdf_metadata["subject"] = args.subject
+
+    if args.merge and args.format != "pdf":
+        log_error(log, "--merge only supports --format pdf.")
+        return EXIT_USER_ERROR
+    if args.merge and args.output is None:
+        log_error(
+            log,
+            "--merge requires -o/--output (a single explicit file "
+            "path): there's no one input to derive a shared output "
+            "name from.",
+        )
+        return EXIT_USER_ERROR
+    if args.merge and (args.output.endswith(("/", "\\")) or os.path.isdir(args.output)):
+        log_error(log, "--merge requires -o/--output to be a file path, not a folder.")
+        return EXIT_USER_ERROR
+
+    raw_inputs: list[str] = []
+    for pat in args.input:
+        expanded = glob.glob(pat)
+        if expanded:
+            raw_inputs.extend(expanded)
+        else:
+            raw_inputs.append(pat)
+
+    with tempfile.TemporaryDirectory(prefix="scanlayer_pdf_") as tmp_dir:
+        try:
+            expanded_inputs: list[str] = []
+            for input_path in raw_inputs:
+                expanded_inputs.extend(_expand_pdf_input(input_path, args.dpi, tmp_dir))
+        except Exception as exc:
+            code = _exit_code_for(exc)
+            log_error(log, f"PDF input expansion failed: {exc}")
+            return code
+
+        if args.dry_run:
+            return _run_dry_run(expanded_inputs, args, log)
+
+        if args.merge:
+            try:
+                convert_merge(
+                    input_paths=expanded_inputs,
+                    output_path=args.output,
+                    lang=args.lang,
+                    dpi=args.dpi,
+                    jpeg_quality=args.jpeg_quality,
+                    char_whitelist=args.whitelist,
+                    char_blacklist=args.blacklist,
+                    pdf_metadata=pdf_metadata,
+                    force=args.force,
+                    orientation=orientation_value,
+                )
+                return EXIT_OK
+            except Exception as exc:
+                code = _exit_code_for(exc)
+                if code == EXIT_UNEXPECTED_ERROR:
+                    import traceback
+                    log_error(log, f"--merge: unexpected error: {type(exc).__name__}: {exc}")
+                    log.debug(traceback.format_exc())
+                else:
+                    log_error(log, f"--merge: {exc}")
+                return code
+
+        is_batch = len(expanded_inputs) > 1
+        failures: list[tuple[str, str]] = []
+        last_exit_code = EXIT_OK
+
+        for input_path in expanded_inputs:
+            try:
+                output_path = _resolve_output_path(
+                    args.output, input_path, is_batch, args.format
+                )
+            except OSError as exc:
+                log_error(log, f"'{input_path}': cannot prepare output path: {exc}")
+                failures.append((input_path, str(exc)))
+                last_exit_code = EXIT_USER_ERROR
+                if not is_batch:
+                    return last_exit_code
+                continue
+
+            try:
+                convert(
+                    input_path=input_path,
+                    output_path=output_path,
+                    lang=args.lang,
+                    dpi=args.dpi,
+                    jpeg_quality=args.jpeg_quality,
+                    char_whitelist=args.whitelist,
+                    char_blacklist=args.blacklist,
+                    pdf_metadata=pdf_metadata,
+                    force=args.force,
+                    orientation=orientation_value,
+                    output_format=args.format,
+                    debug_image=args.debug_image,
+                )
+            except Exception as exc:
+                code = _exit_code_for(exc)
+                if code == EXIT_UNEXPECTED_ERROR:
+                    import traceback
+                    log_error(log, f"'{input_path}': unexpected error: {type(exc).__name__}: {exc}")
+                    log.debug(traceback.format_exc())
+                else:
+                    log_error(log, f"'{input_path}': {exc}")
+                failures.append((input_path, str(exc)))
+                last_exit_code = code
+                if not is_batch:
+                    return last_exit_code
+
+        if failures:
+            if is_batch:
+                log_error(log, f"{len(failures)}/{len(expanded_inputs)} file(s) failed.")
+                return EXIT_PARTIAL_BATCH
+            return last_exit_code
+
+        return EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())