eticket-document-sdk 1.0.0__py3-none-any.whl

eticket_document_sdk/__init__.py

@@ -0,0 +1,71 @@
+"""eticket-document-sdk.
+
+Parse airline e-ticket PDFs into strongly-typed JSON.
+
+Quick start::
+
+    from eticket_document_sdk import ETicketParser
+
+    parser = ETicketParser()
+    booking = parser.parse("ticket.pdf")
+    print(booking.model_dump())
+"""
+
+from __future__ import annotations
+
+from .core.parser import ETicketParser
+from .exceptions import (
+    DocumentReadError,
+    ETicketSDKError,
+    OCRFailedError,
+    ParserError,
+    UnsupportedDocumentError,
+    ValidationError,
+)
+from .models import (
+    Booking,
+    BookingStatus,
+    DocumentType,
+    ExtractionMethod,
+    FlightSegment,
+    ParseResult,
+    Passenger,
+    TaxItem,
+    Ticket,
+)
+from .parsers.airline.registry import (
+    ParserRegistry,
+    get_default_registry,
+    register_parser,
+)
+from .parsers.base import BaseParser
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    # Public entry point
+    "ETicketParser",
+    # Plugin system
+    "BaseParser",
+    "ParserRegistry",
+    "register_parser",
+    "get_default_registry",
+    # Models
+    "Booking",
+    "BookingStatus",
+    "FlightSegment",
+    "Passenger",
+    "Ticket",
+    "TaxItem",
+    "ParseResult",
+    "DocumentType",
+    "ExtractionMethod",
+    # Exceptions
+    "ETicketSDKError",
+    "DocumentReadError",
+    "UnsupportedDocumentError",
+    "OCRFailedError",
+    "ParserError",
+    "ValidationError",
+]

eticket_document_sdk/core/__init__.py

@@ -0,0 +1,14 @@
+"""Core pipeline: parser orchestration, extraction, classification, validation."""
+
+from .classifier import DocumentClassifier
+from .extractor import DocumentExtractor, ExtractionResult
+from .parser import ETicketParser
+from .validator import DocumentValidator
+
+__all__ = [
+    "ETicketParser",
+    "DocumentExtractor",
+    "ExtractionResult",
+    "DocumentClassifier",
+    "DocumentValidator",
+]

eticket_document_sdk/core/classifier.py

@@ -0,0 +1,58 @@
+"""Document classification: choose the right parser for extracted text."""
+
+from __future__ import annotations
+
+from ..models import DocumentType
+from ..parsers.airline.registry import ParserRegistry, get_default_registry
+from ..parsers.base import BaseParser
+from ..pdf import pdf_reader
+from ..utils.logging import get_logger
+
+_logger = get_logger("core.classifier")
+
+# Common image extensions for type detection by filename.
+_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".tif", ".tiff", ".bmp", ".webp"}
+
+# Magic-byte signatures for common image formats.
+_IMAGE_MAGIC = (
+    b"\x89PNG\r\n",  # PNG
+    b"\xff\xd8\xff",  # JPEG
+    b"GIF8",  # GIF
+    b"BM",  # BMP
+)
+
+
+class DocumentClassifier:
+    """Detects input type and selects the best parser for the content."""
+
+    def __init__(self, registry: ParserRegistry | None = None) -> None:
+        self._registry = registry or get_default_registry()
+
+    # -- input type detection ------------------------------------------- #
+    @staticmethod
+    def detect_type_from_bytes(data: bytes) -> DocumentType:
+        if pdf_reader.is_pdf_bytes(data):
+            return DocumentType.PDF
+        if any(data[:8].startswith(magic) for magic in _IMAGE_MAGIC):
+            return DocumentType.IMAGE
+        return DocumentType.UNKNOWN
+
+    @staticmethod
+    def detect_type_from_path(path: str) -> DocumentType:
+        lower = path.lower()
+        if lower.endswith(".pdf"):
+            return DocumentType.PDF
+        if any(lower.endswith(ext) for ext in _IMAGE_EXTS):
+            return DocumentType.IMAGE
+        if lower.endswith((".txt", ".text")):
+            return DocumentType.TEXT
+        return DocumentType.UNKNOWN
+
+    # -- parser selection ----------------------------------------------- #
+    def classify(self, text: str) -> tuple[BaseParser | None, float]:
+        """Return the best-matching parser for ``text`` and its confidence."""
+
+        parser, score = self._registry.best_match(text)
+        if parser:
+            _logger.debug("Classified as %s (score=%.3f)", parser.name, score)
+        return parser, score

eticket_document_sdk/core/extractor.py

@@ -0,0 +1,102 @@
+"""Turn a raw input source into text, choosing text-layer vs OCR.
+
+This is the implementation of pipeline steps 1-4: detect type, extract the text
+layer, measure quality, and fall back to OCR only when necessary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..exceptions import DocumentReadError, UnsupportedDocumentError
+from ..models import DocumentType, ExtractionMethod
+from ..ocr.fallback import OCRFallback
+from ..pdf import text_extractor
+from ..utils.logging import get_logger
+from .classifier import DocumentClassifier
+
+_logger = get_logger("core.extractor")
+
+
+@dataclass
+class ExtractionResult:
+    """Outcome of the text-acquisition stage."""
+
+    text: str
+    document_type: DocumentType
+    method: ExtractionMethod
+    quality: float
+
+
+class DocumentExtractor:
+    """Acquires text from PDF / image / raw-text inputs."""
+
+    def __init__(
+        self,
+        *,
+        ocr: OCRFallback,
+        classifier: DocumentClassifier | None = None,
+        text_quality_threshold: float = 0.35,
+        min_text_length: int = 80,
+    ) -> None:
+        self._ocr = ocr
+        self._classifier = classifier or DocumentClassifier()
+        self._threshold = text_quality_threshold
+        self._min_length = min_text_length
+
+    def extract_from_bytes(
+        self, data: bytes, *, document_type: DocumentType | None = None
+    ) -> ExtractionResult:
+        doc_type = document_type or self._classifier.detect_type_from_bytes(data)
+
+        if doc_type == DocumentType.PDF:
+            return self._extract_pdf(data)
+        if doc_type == DocumentType.IMAGE:
+            return self._extract_image(data)
+        raise UnsupportedDocumentError(
+            f"Unsupported document type: {doc_type.value}. "
+            "Provide a PDF, an image, or use parse_text() for raw text."
+        )
+
+    def extract_from_text(self, text: str) -> ExtractionResult:
+        if not text or not text.strip():
+            raise DocumentReadError("Empty text supplied to parse_text().")
+        return ExtractionResult(
+            text=text,
+            document_type=DocumentType.TEXT,
+            method=ExtractionMethod.RAW_TEXT,
+            quality=text_extractor.measure_quality(text, min_length=self._min_length),
+        )
+
+    # -- internals ------------------------------------------------------ #
+    def _extract_pdf(self, data: bytes) -> ExtractionResult:
+        text = text_extractor.extract_text(data)
+        quality = text_extractor.measure_quality(text, min_length=self._min_length)
+        _logger.debug("PDF text-layer quality=%.3f length=%d", quality, len(text))
+
+        if quality >= self._threshold and len(text) >= self._min_length:
+            return ExtractionResult(
+                text=text,
+                document_type=DocumentType.PDF,
+                method=ExtractionMethod.TEXT_LAYER,
+                quality=quality,
+            )
+
+        _logger.info("Text layer insufficient (q=%.3f); attempting OCR fallback", quality)
+        ocr_text = self._ocr.run_on_pdf(data)
+        return ExtractionResult(
+            text=ocr_text,
+            document_type=DocumentType.PDF,
+            method=ExtractionMethod.OCR,
+            quality=text_extractor.measure_quality(ocr_text, min_length=self._min_length),
+        )
+
+    def _extract_image(self, data: bytes) -> ExtractionResult:
+        # Images have no text layer; go straight to OCR.
+        ocr_text = self._ocr.run_on_image(data)
+        return ExtractionResult(
+            text=ocr_text,
+            document_type=DocumentType.IMAGE,
+            method=ExtractionMethod.OCR,
+            quality=text_extractor.measure_quality(ocr_text, min_length=self._min_length),
+        )

eticket_document_sdk/core/parser.py

@@ -0,0 +1,155 @@
+"""Public SDK entry point: :class:`ETicketParser`.
+
+Orchestrates the full pipeline (detect -> extract -> classify -> parse ->
+validate -> return) behind a deliberately tiny API:
+
+    parser = ETicketParser()
+    booking = parser.parse("ticket.pdf")
+    print(booking.model_dump())
+
+The parser instance is reusable and thread-safe: the OCR model, compiled regex
+and parser registry are all created once and shared.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from ..exceptions import ParserError
+from ..models import Booking, ParseResult
+from ..ocr.fallback import OCRFallback
+from ..parsers.airline.registry import ParserRegistry, get_default_registry
+from ..utils.logging import configure_logging, get_logger
+from .classifier import DocumentClassifier
+from .extractor import DocumentExtractor, ExtractionResult
+from .validator import DocumentValidator
+
+_logger = get_logger("core.parser")
+
+# Fields used to compute a heuristic confidence/completeness score.
+_KEY_FIELDS = ("booking_code", "ticket_number", "currency", "total_price")
+
+
+class ETicketParser:
+    """Parse airline e-ticket documents into strongly-typed :class:`Booking`s."""
+
+    def __init__(
+        self,
+        *,
+        enable_ocr: bool = True,
+        ocr_langs: list[str] | None = None,
+        debug: bool = False,
+        strict_validation: bool = False,
+        text_quality_threshold: float = 0.35,
+        registry: ParserRegistry | None = None,
+    ) -> None:
+        if debug:
+            configure_logging(logging.DEBUG)
+
+        self.debug = debug
+        self.strict_validation = strict_validation
+        self._registry = registry or get_default_registry()
+
+        self._ocr = OCRFallback(
+            enabled=enable_ocr, languages=ocr_langs or ["vi", "en", "ja"]
+        )
+        self._classifier = DocumentClassifier(self._registry)
+        self._extractor = DocumentExtractor(
+            ocr=self._ocr,
+            classifier=self._classifier,
+            text_quality_threshold=text_quality_threshold,
+        )
+        self._validator = DocumentValidator()
+
+    # ------------------------------------------------------------------ #
+    # Public API (returns Booking)
+    # ------------------------------------------------------------------ #
+    def parse(self, source: str | Path) -> Booking:
+        """Parse a document from a file path. Returns a :class:`Booking`."""
+
+        return self.parse_detailed(source).booking  # type: ignore[return-value]
+
+    def parse_bytes(self, data: bytes) -> Booking:
+        """Parse a document from raw bytes (PDF or image)."""
+
+        return self.parse_bytes_detailed(data).booking  # type: ignore[return-value]
+
+    def parse_text(self, text: str) -> Booking:
+        """Parse already-extracted raw text (no PDF/OCR involved)."""
+
+        return self.parse_text_detailed(text).booking  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------ #
+    # Public API (returns ParseResult envelope)
+    # ------------------------------------------------------------------ #
+    def parse_detailed(self, source: str | Path) -> ParseResult:
+        """Like :meth:`parse` but returns the full :class:`ParseResult`."""
+
+        from ..pdf import pdf_reader
+
+        path = str(source)
+        data = pdf_reader.read_bytes(path)
+        doc_type = self._classifier.detect_type_from_path(path)
+        if doc_type.name == "TEXT":
+            return self.parse_text_detailed(data.decode("utf-8", errors="replace"))
+        extraction = self._extractor.extract_from_bytes(
+            data, document_type=None if doc_type.name == "UNKNOWN" else doc_type
+        )
+        return self._finish(extraction)
+
+    def parse_bytes_detailed(self, data: bytes) -> ParseResult:
+        extraction = self._extractor.extract_from_bytes(data)
+        return self._finish(extraction)
+
+    def parse_text_detailed(self, text: str) -> ParseResult:
+        extraction = self._extractor.extract_from_text(text)
+        return self._finish(extraction)
+
+    # ------------------------------------------------------------------ #
+    # Pipeline tail: classify -> parse -> validate -> envelope
+    # ------------------------------------------------------------------ #
+    def _finish(self, extraction: ExtractionResult) -> ParseResult:
+        parser, score = self._classifier.classify(extraction.text)
+        if parser is None:
+            raise ParserError(
+                "No parser could handle this document. "
+                "Register an airline parser or check the input."
+            )
+
+        _logger.info(
+            "Parsing with %s (match=%.3f, method=%s)",
+            parser.name,
+            score,
+            extraction.method.value,
+        )
+        try:
+            booking = parser.parse(extraction.text)
+        except ParserError:
+            raise
+        except Exception as exc:  # surface parser bugs as ParserError
+            raise ParserError(
+                f"Parser {parser.name!r} failed.", details=str(exc)
+            ) from exc
+
+        warnings = self._validator.validate(booking, strict=self.strict_validation)
+        confidence = _completeness(booking)
+
+        return ParseResult(
+            success=True,
+            document_type=extraction.document_type,
+            extraction_method=extraction.method,
+            parser=parser.name,
+            confidence=confidence,
+            booking=booking,
+            warnings=warnings,
+        )
+
+
+def _completeness(booking: Booking) -> float:
+    """Fraction of key fields present, lightly weighted by segment presence."""
+
+    present = sum(1 for f in _KEY_FIELDS if getattr(booking, f, None) is not None)
+    field_score = present / len(_KEY_FIELDS)
+    segment_score = 1.0 if booking.segments else 0.0
+    return round(0.7 * field_score + 0.3 * segment_score, 4)

eticket_document_sdk/core/validator.py

@@ -0,0 +1,64 @@
+"""Business-rule validation for parsed bookings.
+
+Pydantic validates field *types*; this layer validates cross-field *business*
+rules (ticket number length, currency sanity, presence of segments) and either
+raises :class:`ValidationError` (strict mode) or returns a list of warnings.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..exceptions import ValidationError
+from ..models import Booking
+from ..utils.currency import is_valid_currency
+from ..utils.logging import get_logger
+
+_logger = get_logger("core.validator")
+
+_TICKET_RE = re.compile(r"^\d{13}$")
+_PNR_RE = re.compile(r"^[A-Z0-9]{6}$")
+_FLIGHT_RE = re.compile(r"^([A-Z]{2}|[A-Z]\d)\d{1,4}$")
+
+
+class DocumentValidator:
+    """Validates a :class:`Booking` against airline-ticket business rules."""
+
+    def validate(self, booking: Booking, *, strict: bool = False) -> list[str]:
+        """Return a list of validation issues.
+
+        In ``strict`` mode, raises :class:`ValidationError` if any issue is
+        found; otherwise returns the issues as warnings for the caller to log.
+        """
+
+        issues: list[str] = []
+        t = booking.ticket
+
+        if not t.booking_code:
+            issues.append("Missing booking code (PNR).")
+        elif not _PNR_RE.match(t.booking_code):
+            issues.append(f"Invalid booking code format: {t.booking_code!r}.")
+
+        if not t.ticket_number:
+            issues.append("Missing ticket number.")
+        elif not _TICKET_RE.match(t.ticket_number):
+            issues.append(f"Invalid ticket number format: {t.ticket_number!r}.")
+
+        if t.currency and not is_valid_currency(t.currency):
+            issues.append(f"Invalid currency code: {t.currency!r}.")
+
+        if t.total_price is not None and t.total_price < 0:
+            issues.append("Total price is negative.")
+
+        if not booking.segments:
+            issues.append("No flight segments found.")
+        for seg in booking.segments:
+            if seg.flight_number and not _FLIGHT_RE.match(seg.flight_number):
+                issues.append(f"Invalid flight number format: {seg.flight_number!r}.")
+
+        if strict and issues:
+            raise ValidationError("Booking failed validation.", errors=issues)
+
+        for issue in issues:
+            _logger.warning("Validation: %s", issue)
+        return issues

eticket_document_sdk/data/__init__.py

@@ -0,0 +1,5 @@
+"""Static data tables used by parsers (airport directories, etc.)."""
+
+from .airports import resolve_airport
+
+__all__ = ["resolve_airport"]

eticket_document_sdk/data/airports.py

@@ -0,0 +1,70 @@
+"""Airport name -> IATA resolution.
+
+E-ticket receipts frequently print full airport names ("TOKYO NARITA INTL, JP")
+rather than IATA codes. This module resolves those names to IATA codes using a
+keyword-matching strategy that is resilient to ordering and punctuation.
+
+The table is intentionally a curated subset of high-traffic airports plus every
+airport required by the bundled test fixtures. It is data, not logic — extend it
+freely without touching the parsers.
+"""
+
+from __future__ import annotations
+
+# IATA code -> tuple of distinguishing keyword sets. A name matches a code when
+# *all* keywords in any one set are present (case-insensitive) in the name.
+_AIRPORT_KEYWORDS: dict[str, tuple[tuple[str, ...], ...]] = {
+    "NRT": (("tokyo", "narita"), ("narita",)),
+    "HND": (("tokyo", "haneda"), ("haneda",)),
+    "HAN": (("hanoi", "noi bai"), ("noi bai",)),
+    "SGN": (("ho chi minh", "tan son nhat"), ("tan son nhat",), ("saigon",)),
+    "DAD": (("da nang",), ("danang",)),
+    "CDG": (("paris", "charles de gaulle"), ("charles de gaulle",)),
+    "ORY": (("paris", "orly"),),
+    "LHR": (("london", "heathrow"), ("heathrow",)),
+    "LGW": (("london", "gatwick"),),
+    "FRA": (("frankfurt",),),
+    "AMS": (("amsterdam", "schiphol"), ("schiphol",)),
+    "ICN": (("seoul", "incheon"), ("incheon",)),
+    "GMP": (("seoul", "gimpo"),),
+    "PEK": (("beijing", "capital"),),
+    "PKX": (("beijing", "daxing"),),
+    "PVG": (("shanghai", "pudong"), ("pudong",)),
+    "HKG": (("hong kong",),),
+    "TPE": (("taipei", "taoyuan"), ("taoyuan",)),
+    "SIN": (("singapore", "changi"), ("changi",)),
+    "BKK": (("bangkok", "suvarnabhumi"), ("suvarnabhumi",)),
+    "DMK": (("bangkok", "don muang"),),
+    "KUL": (("kuala lumpur",),),
+    "SYD": (("sydney",),),
+    "MEL": (("melbourne",),),
+    "LAX": (("los angeles",),),
+    "SFO": (("san francisco",),),
+    "JFK": (("new york", "kennedy"), ("john f kennedy",)),
+    "DXB": (("dubai",),),
+    "DOH": (("doha", "hamad"),),
+}
+
+
+def resolve_airport(name: str | None) -> str | None:
+    """Resolve a printed airport name to its IATA code.
+
+    Returns the 3-letter IATA code, or ``None`` when no confident match exists
+    (callers then fall back to the raw name).
+    """
+
+    if not name:
+        return None
+
+    text = " ".join(name.lower().replace(",", " ").split())
+
+    # Fast path: an explicit 3-letter IATA token already present in the name.
+    for token in text.upper().split():
+        if len(token) == 3 and token.isalpha() and token in _AIRPORT_KEYWORDS:
+            return token
+
+    for code, keyword_sets in _AIRPORT_KEYWORDS.items():
+        for keywords in keyword_sets:
+            if all(kw in text for kw in keywords):
+                return code
+    return None

eticket_document_sdk/exceptions/__init__.py

@@ -0,0 +1,19 @@
+"""Public exception surface for the SDK."""
+
+from .parser_error import (
+    DocumentReadError,
+    ETicketSDKError,
+    OCRFailedError,
+    ParserError,
+    UnsupportedDocumentError,
+)
+from .validation_error import ValidationError
+
+__all__ = [
+    "ETicketSDKError",
+    "DocumentReadError",
+    "UnsupportedDocumentError",
+    "OCRFailedError",
+    "ParserError",
+    "ValidationError",
+]

eticket_document_sdk/exceptions/parser_error.py

@@ -0,0 +1,40 @@
+"""Custom exceptions for the document/parsing pipeline.
+
+All SDK exceptions derive from :class:`ETicketSDKError` so callers can catch the
+whole family with a single ``except`` clause while still being able to handle
+specific failure modes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ETicketSDKError(Exception):
+    """Base class for every exception raised by the SDK."""
+
+    def __init__(self, message: str, *, details: Any | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        if self.details:
+            return f"{self.message} ({self.details})"
+        return self.message
+
+
+class DocumentReadError(ETicketSDKError):
+    """Raised when a document cannot be opened or read (corrupt/empty file)."""
+
+
+class UnsupportedDocumentError(ETicketSDKError):
+    """Raised when the input type or document layout is not supported."""
+
+
+class OCRFailedError(ETicketSDKError):
+    """Raised when OCR fallback is required but unavailable or fails."""
+
+
+class ParserError(ETicketSDKError):
+    """Raised when a parser cannot extract the minimum required fields."""

eticket_document_sdk/exceptions/validation_error.py

@@ -0,0 +1,25 @@
+"""Validation-related exceptions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .parser_error import ETicketSDKError
+
+
+class ValidationError(ETicketSDKError):
+    """Raised when extracted data fails business-rule validation.
+
+    ``errors`` carries a list of human-readable field-level problems so the
+    caller can surface every issue at once instead of one at a time.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        errors: list[str] | None = None,
+        details: Any | None = None,
+    ) -> None:
+        super().__init__(message, details=details)
+        self.errors: list[str] = errors or []

eticket_document_sdk/models/__init__.py

@@ -0,0 +1,19 @@
+"""Domain models (Pydantic v2)."""
+
+from .booking import Booking, BookingStatus
+from .flight import FlightSegment
+from .passenger import Passenger
+from .response import DocumentType, ExtractionMethod, ParseResult
+from .ticket import TaxItem, Ticket
+
+__all__ = [
+    "Passenger",
+    "FlightSegment",
+    "Ticket",
+    "TaxItem",
+    "Booking",
+    "BookingStatus",
+    "ParseResult",
+    "DocumentType",
+    "ExtractionMethod",
+]