xgen-doc2chunk 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

xgen_doc2chunk/core/processor/hwpx_helper/hwpx_table_processor.py

@@ -0,0 +1,220 @@
+# xgen_doc2chunk/core/processor/hwpx_helper/hwpx_table_processor.py
+"""
+HWPX Table Processor
+
+Formats TableData into HTML/Markdown/Text output for HWPX documents.
+Extends the base TableProcessor with HWPX-specific formatting options.
+
+Key Features:
+- HTML output with border attributes for backward compatibility
+- Special handling for 1x1 container tables
+- Special handling for single column tables
+- Post-processing for HWPX-specific requirements
+
+Usage:
+    from xgen_doc2chunk.core.processor.hwpx_helper.hwpx_table_processor import (
+        HWPXTableProcessor,
+        create_hwpx_table_processor,
+    )
+    
+    processor = HWPXTableProcessor()
+    html = processor.format_table(table_data)
+"""
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+from xgen_doc2chunk.core.functions.table_extractor import TableData
+from xgen_doc2chunk.core.functions.table_processor import (
+    TableProcessor,
+    TableProcessorConfig,
+    TableOutputFormat,
+)
+
+logger = logging.getLogger("document-processor")
+
+
+@dataclass
+class HWPXTableProcessorConfig(TableProcessorConfig):
+    """Configuration for HWPX table processing.
+    
+    Extends TableProcessorConfig with HWPX-specific options.
+    
+    Attributes:
+        add_border: Whether to add border='1' attribute to HTML tables
+        collapse_single_cell: Whether to collapse 1x1 tables to plain text
+        collapse_single_column: Whether to collapse single-column tables to line-separated text
+    """
+    add_border: bool = True
+    collapse_single_cell: bool = True
+    collapse_single_column: bool = True
+
+
+class HWPXTableProcessor(TableProcessor):
+    """HWPX-specific table processor.
+    
+    Extends TableProcessor with HWPX-specific formatting:
+    - Adds border='1' to HTML tables for backward compatibility
+    - Collapses 1x1 container tables to plain text
+    - Collapses single-column tables to line-separated text
+    
+    Usage:
+        processor = HWPXTableProcessor()
+        html = processor.format_table(table_data)
+    """
+    
+    def __init__(self, config: Optional[HWPXTableProcessorConfig] = None):
+        """Initialize the HWPX table processor.
+        
+        Args:
+            config: HWPX table processing configuration
+        """
+        if config is None:
+            config = HWPXTableProcessorConfig()
+        super().__init__(config)
+        self.hwpx_config = config
+    
+    def format_table(self, table: TableData) -> str:
+        """Format a table with HWPX-specific handling.
+        
+        Handles special cases before delegating to base class:
+        - 1x1 tables: Return cell content only (container tables)
+        - Single column tables: Return as line-separated text
+        
+        Args:
+            table: TableData to format
+            
+        Returns:
+            Formatted table string
+        """
+        if not table or not table.rows:
+            return ""
+        
+        # Special case: 1x1 table (container table)
+        if (self.hwpx_config.collapse_single_cell and 
+            table.num_rows == 1 and table.num_cols == 1):
+            if table.rows and table.rows[0]:
+                return table.rows[0][0].content
+            return ""
+        
+        # Special case: Single column table
+        if (self.hwpx_config.collapse_single_column and 
+            table.num_cols == 1):
+            text_items = []
+            for row in table.rows:
+                if row and row[0].content:
+                    text_items.append(row[0].content)
+            if text_items:
+                return "\n\n".join(text_items)
+            return ""
+        
+        # Normal table processing
+        return super().format_table(table)
+    
+    def format_table_as_html(self, table: TableData) -> str:
+        """Format table as HTML with HWPX-specific attributes.
+        
+        Adds border='1' attribute for backward compatibility.
+        
+        Args:
+            table: TableData to format
+            
+        Returns:
+            HTML table string
+        """
+        # Check for special cases first
+        if not table or not table.rows:
+            return ""
+        
+        # 1x1 table handling
+        if (self.hwpx_config.collapse_single_cell and 
+            table.num_rows == 1 and table.num_cols == 1):
+            if table.rows and table.rows[0]:
+                return table.rows[0][0].content
+            return ""
+        
+        # Single column table handling
+        if (self.hwpx_config.collapse_single_column and 
+            table.num_cols == 1):
+            text_items = []
+            for row in table.rows:
+                if row and row[0].content:
+                    text_items.append(row[0].content)
+            if text_items:
+                return "\n\n".join(text_items)
+            return ""
+        
+        # Generate HTML using base class
+        html = super().format_table_as_html(table)
+        
+        # Post-process: Add border attribute
+        if self.hwpx_config.add_border:
+            html = html.replace("<table>", "<table border='1'>")
+        
+        return html
+
+
+# Default configuration
+DEFAULT_HWPX_PROCESSOR_CONFIG = HWPXTableProcessorConfig(
+    output_format=TableOutputFormat.HTML,
+    clean_whitespace=True,
+    preserve_merged_cells=True,
+    add_border=True,
+    collapse_single_cell=True,
+    collapse_single_column=True,
+)
+
+
+# Module-level default processor (lazy initialized)
+_default_processor: Optional[HWPXTableProcessor] = None
+
+
+def get_default_processor() -> HWPXTableProcessor:
+    """Get or create the default HWPX table processor.
+    
+    Returns:
+        Configured HWPXTableProcessor instance
+    """
+    global _default_processor
+    if _default_processor is None:
+        _default_processor = HWPXTableProcessor(DEFAULT_HWPX_PROCESSOR_CONFIG)
+    return _default_processor
+
+
+def create_hwpx_table_processor(
+    config: Optional[HWPXTableProcessorConfig] = None
+) -> HWPXTableProcessor:
+    """Create a HWPX table processor instance.
+    
+    Args:
+        config: HWPX table processing configuration
+        
+    Returns:
+        Configured HWPXTableProcessor instance
+    """
+    return HWPXTableProcessor(config)
+
+
+def format_table_as_html(table: TableData) -> str:
+    """Convenience function to format a table as HTML.
+    
+    Uses the default HWPX table processor.
+    
+    Args:
+        table: TableData to format
+        
+    Returns:
+        HTML table string
+    """
+    processor = get_default_processor()
+    return processor.format_table_as_html(table)
+
+
+__all__ = [
+    'HWPXTableProcessor',
+    'HWPXTableProcessorConfig',
+    'DEFAULT_HWPX_PROCESSOR_CONFIG',
+    'create_hwpx_table_processor',
+    'get_default_processor',
+    'format_table_as_html',
+]

xgen_doc2chunk/core/processor/image_file_handler.py

@@ -0,0 +1,212 @@
+# xgen_doc2chunk/core/processor/image_file_handler.py
+"""
+Image File Handler - Image File Processor
+
+Class-based handler for image files (jpg, jpeg, png, gif, bmp, webp).
+Converts images to text using OCR engine when available.
+If no OCR engine is provided, returns a placeholder or empty string.
+"""
+import logging
+import os
+from typing import Any, Optional, TYPE_CHECKING
+
+from xgen_doc2chunk.core.processor.base_handler import BaseHandler
+from xgen_doc2chunk.core.functions.chart_extractor import BaseChartExtractor, NullChartExtractor
+from xgen_doc2chunk.core.processor.image_file_helper.image_file_image_processor import ImageFileImageProcessor
+from xgen_doc2chunk.core.functions.img_processor import ImageProcessor
+
+if TYPE_CHECKING:
+    from xgen_doc2chunk.core.document_processor import CurrentFile
+    from xgen_doc2chunk.ocr.base import BaseOCR
+
+logger = logging.getLogger("document-processor")
+
+
+# Supported image extensions
+SUPPORTED_IMAGE_EXTENSIONS = frozenset(['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp'])
+
+
+class ImageFileHandler(BaseHandler):
+    """
+    Image File Processing Handler Class.
+
+    Processes standalone image files by converting them to text using OCR.
+    Requires an OCR engine to be provided for actual text extraction.
+
+    Args:
+        config: Configuration dictionary (passed from DocumentProcessor)
+        image_processor: ImageProcessor instance (passed from DocumentProcessor)
+        page_tag_processor: PageTagProcessor instance (passed from DocumentProcessor)
+        ocr_engine: OCR engine instance (BaseOCR subclass) for image-to-text conversion
+
+    Example:
+        >>> from xgen_doc2chunk.ocr.ocr_engine import OpenAIOCR
+        >>> ocr = OpenAIOCR(api_key="sk-...", model="gpt-4o")
+        >>> handler = ImageFileHandler(ocr_engine=ocr)
+        >>> text = handler.extract_text(current_file)
+    """
+
+    def _create_file_converter(self):
+        """Create image-file-specific file converter."""
+        from xgen_doc2chunk.core.processor.image_file_helper.image_file_converter import ImageFileConverter
+        return ImageFileConverter()
+
+    def _create_preprocessor(self):
+        """Create image-file-specific preprocessor."""
+        from xgen_doc2chunk.core.processor.image_file_helper.image_file_preprocessor import ImageFilePreprocessor
+        return ImageFilePreprocessor()
+
+    def _create_chart_extractor(self) -> BaseChartExtractor:
+        """Image files do not contain charts. Return NullChartExtractor."""
+        return NullChartExtractor(self._chart_processor)
+
+    def _create_metadata_extractor(self):
+        """Image files do not have document metadata. Return None (uses NullMetadataExtractor)."""
+        return None
+
+    def _create_format_image_processor(self) -> ImageProcessor:
+        """Create image-file-specific image processor."""
+        return ImageFileImageProcessor()
+
+    def __init__(
+        self,
+        config: Optional[dict] = None,
+        image_processor: Optional[Any] = None,
+        page_tag_processor: Optional[Any] = None,
+        chart_processor: Optional[Any] = None,
+        ocr_engine: Optional["BaseOCR"] = None
+    ):
+        """
+        Initialize ImageFileHandler.
+
+        Args:
+            config: Configuration dictionary (passed from DocumentProcessor)
+            image_processor: ImageProcessor instance (passed from DocumentProcessor)
+            page_tag_processor: PageTagProcessor instance (passed from DocumentProcessor)
+            chart_processor: ChartProcessor instance (passed from DocumentProcessor)
+            ocr_engine: OCR engine instance (BaseOCR subclass) for image-to-text conversion.
+                       If None, images cannot be converted to text.
+        """
+        super().__init__(
+            config=config,
+            image_processor=image_processor,
+            page_tag_processor=page_tag_processor,
+            chart_processor=chart_processor
+        )
+        self._ocr_engine = ocr_engine
+
+    @property
+    def ocr_engine(self) -> Optional["BaseOCR"]:
+        """Current OCR engine instance."""
+        return self._ocr_engine
+
+    @ocr_engine.setter
+    def ocr_engine(self, engine: Optional["BaseOCR"]) -> None:
+        """Set OCR engine instance."""
+        self._ocr_engine = engine
+
+    def extract_text(
+        self,
+        current_file: "CurrentFile",
+        extract_metadata: bool = True,
+        **kwargs
+    ) -> str:
+        """
+        Extract text from image file using OCR.
+
+        Converts the image file to text using the configured OCR engine.
+        If no OCR engine is available, returns an error message.
+
+        Args:
+            current_file: CurrentFile dict containing file info and binary data
+            extract_metadata: Whether to extract metadata (not used for images)
+            **kwargs: Additional options (not used)
+
+        Returns:
+            Extracted text from image, or error message if OCR is not available
+
+        Raises:
+            ValueError: If OCR engine is not configured
+        """
+        file_path = current_file.get("file_path", "unknown")
+        file_name = current_file.get("file_name", "unknown")
+        file_extension = current_file.get("file_extension", "").lower()
+        file_data = current_file.get("file_data", b"")
+
+        self.logger.info(f"Processing image file: {file_name}")
+
+        # Step 1: No file_converter for image files (direct processing)
+        # Step 2: Preprocess - clean_content is the TRUE SOURCE
+        preprocessed = self.preprocess(file_data)
+        file_data = preprocessed.clean_content  # TRUE SOURCE
+
+        # Validate file extension
+        if file_extension not in SUPPORTED_IMAGE_EXTENSIONS:
+            self.logger.warning(f"Unsupported image extension: {file_extension}")
+            return f"[Unsupported image format: {file_extension}]"
+
+        # If OCR engine is not available, return image tag format
+        # This allows the image to be processed later when OCR is available
+        if self._ocr_engine is None:
+            self.logger.debug(f"OCR engine not available, returning image tag: {file_name}")
+            # Use ImageProcessor's tag format (e.g., [Image:path] or custom format)
+            return self._build_image_tag(file_path)
+
+        # Use OCR engine to convert image to text
+        try:
+            # Use the file path directly for OCR conversion
+            result = self._ocr_engine.convert_image_to_text(file_path)
+
+            if result is None:
+                self.logger.error(f"OCR returned None for image: {file_name}")
+                return f"[Image OCR failed: {file_name}]"
+
+            if result.startswith("[Image conversion error:"):
+                self.logger.error(f"OCR error for image {file_name}: {result}")
+                return result
+
+            self.logger.info(f"Successfully extracted text from image: {file_name}")
+            return result
+
+        except Exception as e:
+            self.logger.error(f"Error processing image {file_name}: {e}")
+            return f"[Image processing error: {str(e)}]"
+
+    def is_supported(self, file_extension: str) -> bool:
+        """
+        Check if file extension is supported.
+
+        Args:
+            file_extension: File extension (with or without dot)
+
+        Returns:
+            True if extension is supported, False otherwise
+        """
+        ext = file_extension.lower().lstrip('.')
+        return ext in SUPPORTED_IMAGE_EXTENSIONS
+
+    def _build_image_tag(self, file_path: str) -> str:
+        """
+        Build image tag using ImageProcessor's tag format.
+
+        Uses the configured tag_prefix and tag_suffix from ImageProcessor
+        to create a consistent image tag format.
+
+        Args:
+            file_path: Path to the image file
+
+        Returns:
+            Image tag string (e.g., "[Image:path]" or custom format)
+        """
+        # Normalize path separators (Windows -> Unix style)
+        path_str = file_path.replace("\\", "/")
+
+        # Use ImageProcessor's tag format
+        prefix = self.image_processor.config.tag_prefix
+        suffix = self.image_processor.config.tag_suffix
+
+        return f"{prefix}{path_str}{suffix}"
+
+
+__all__ = ["ImageFileHandler", "SUPPORTED_IMAGE_EXTENSIONS"]
+

xgen_doc2chunk/core/processor/image_file_helper/__init__.py

@@ -0,0 +1,17 @@
+# xgen_doc2chunk/core/processor/image_file_helper/__init__.py
+"""
+Image File Helper 모듈
+
+이미지 파일 처리에 필요한 유틸리티를 제공합니다.
+
+모듈 구성:
+- image_file_image_processor: 이미지 파일용 이미지 프로세서
+"""
+
+from xgen_doc2chunk.core.processor.image_file_helper.image_file_image_processor import (
+    ImageFileImageProcessor,
+)
+
+__all__ = [
+    "ImageFileImageProcessor",
+]

xgen_doc2chunk/core/processor/image_file_helper/image_file_converter.py

@@ -0,0 +1,69 @@
+# xgen_doc2chunk/core/processor/image_file_helper/image_file_converter.py
+"""
+ImageFileConverter - Image file format converter
+
+Pass-through converter for image files.
+Images are kept as binary data.
+"""
+from typing import Any, Optional, BinaryIO
+
+from xgen_doc2chunk.core.functions.file_converter import NullFileConverter
+
+
+class ImageFileConverter(NullFileConverter):
+    """
+    Image file converter.
+    
+    Images don't need conversion - returns raw bytes.
+    This is a pass-through converter.
+    """
+    
+    # Common image magic numbers
+    MAGIC_JPEG = b'\xff\xd8\xff'
+    MAGIC_PNG = b'\x89PNG\r\n\x1a\n'
+    MAGIC_GIF = b'GIF8'
+    MAGIC_BMP = b'BM'
+    MAGIC_WEBP = b'RIFF'
+    
+    def get_format_name(self) -> str:
+        """Return format name."""
+        return "Image File"
+    
+    def validate(self, file_data: bytes) -> bool:
+        """Validate if data is an image."""
+        if not file_data or len(file_data) < 4:
+            return False
+        
+        return (
+            file_data[:3] == self.MAGIC_JPEG or
+            file_data[:8] == self.MAGIC_PNG or
+            file_data[:4] == self.MAGIC_GIF or
+            file_data[:2] == self.MAGIC_BMP or
+            file_data[:4] == self.MAGIC_WEBP
+        )
+    
+    def detect_image_type(self, file_data: bytes) -> Optional[str]:
+        """
+        Detect image type from binary data.
+        
+        Args:
+            file_data: Raw binary image data
+            
+        Returns:
+            Image type string (jpeg, png, gif, bmp, webp) or None
+        """
+        if not file_data or len(file_data) < 8:
+            return None
+        
+        if file_data[:3] == self.MAGIC_JPEG:
+            return "jpeg"
+        elif file_data[:8] == self.MAGIC_PNG:
+            return "png"
+        elif file_data[:4] == self.MAGIC_GIF:
+            return "gif"
+        elif file_data[:2] == self.MAGIC_BMP:
+            return "bmp"
+        elif file_data[:4] == self.MAGIC_WEBP:
+            return "webp"
+        return None
+

xgen_doc2chunk/core/processor/image_file_helper/image_file_image_processor.py

@@ -0,0 +1,123 @@
+# xgen_doc2chunk/core/processor/image_file_helper/image_file_image_processor.py
+"""
+Image File Image Processor
+
+Provides image-file-specific processing that inherits from ImageProcessor.
+Handles standalone image files (jpg, png, gif, bmp, webp, etc.).
+"""
+import logging
+from typing import Any, Optional
+
+from xgen_doc2chunk.core.functions.img_processor import ImageProcessor
+from xgen_doc2chunk.core.functions.storage_backend import BaseStorageBackend
+
+logger = logging.getLogger("xgen_doc2chunk.image_processor.image_file")
+
+
+class ImageFileImageProcessor(ImageProcessor):
+    """
+    Image file-specific image processor.
+    
+    Inherits from ImageProcessor and provides image file-specific processing.
+    Handles standalone image files that are the document themselves.
+    
+    Handles:
+    - Standalone image files (jpg, jpeg, png, gif, bmp, webp)
+    - Image saving with metadata preservation
+    - Format conversion if needed
+    
+    Example:
+        processor = ImageFileImageProcessor()
+        
+        # Process standalone image
+        tag = processor.process_image(image_data, source_path="/path/to/image.png")
+        
+        # Process with original filename
+        tag = processor.process_standalone_image(image_data, original_name="photo.jpg")
+    """
+    
+    def __init__(
+        self,
+        directory_path: str = "temp/images",
+        tag_prefix: str = "[Image:",
+        tag_suffix: str = "]",
+        storage_backend: Optional[BaseStorageBackend] = None,
+        preserve_original_name: bool = False,
+    ):
+        """
+        Initialize ImageFileImageProcessor.
+        
+        Args:
+            directory_path: Image save directory
+            tag_prefix: Tag prefix for image references
+            tag_suffix: Tag suffix for image references
+            storage_backend: Storage backend for saving images
+            preserve_original_name: Whether to preserve original filename
+        """
+        super().__init__(
+            directory_path=directory_path,
+            tag_prefix=tag_prefix,
+            tag_suffix=tag_suffix,
+            storage_backend=storage_backend,
+        )
+        self._preserve_original_name = preserve_original_name
+    
+    @property
+    def preserve_original_name(self) -> bool:
+        """Whether to preserve original filename."""
+        return self._preserve_original_name
+    
+    def process_image(
+        self,
+        image_data: bytes,
+        source_path: Optional[str] = None,
+        original_name: Optional[str] = None,
+        **kwargs
+    ) -> Optional[str]:
+        """
+        Process and save image file data.
+        
+        Args:
+            image_data: Raw image binary data
+            source_path: Original file path
+            original_name: Original filename
+            **kwargs: Additional options
+            
+        Returns:
+            Image tag string or None if processing failed
+        """
+        # Use original name if preserve option is set
+        custom_name = None
+        if self._preserve_original_name and original_name:
+            import os
+            custom_name = os.path.splitext(original_name)[0]
+        elif source_path:
+            import os
+            custom_name = os.path.splitext(os.path.basename(source_path))[0]
+        
+        return self.save_image(image_data, custom_name=custom_name)
+    
+    def process_standalone_image(
+        self,
+        image_data: bytes,
+        original_name: Optional[str] = None,
+        **kwargs
+    ) -> Optional[str]:
+        """
+        Process standalone image file.
+        
+        Specialized method for processing image files that are the document.
+        
+        Args:
+            image_data: Raw image binary data
+            original_name: Original filename
+            **kwargs: Additional options
+            
+        Returns:
+            Image tag string or None if processing failed
+        """
+        return self.process_image(
+            image_data,
+            original_name=original_name,
+            **kwargs
+        )