dochan 0.1.0__py3-none-any.whl

dochan/__init__.py

@@ -0,0 +1,9 @@
+"""dochan — HWP/HWPX 문서 파서, AI/LLM 최적 Markdown 변환"""
+__version__ = "0.1.0"
+
+from .reader import Dochan
+
+# 하위 호환 별칭
+HWPReader = Dochan
+
+__all__ = ['Dochan', 'HWPReader']

dochan/batch.py

@@ -0,0 +1,154 @@
+"""
+batch.py — 배치 처리
+다수 HWP 파일의 병렬 변환
+"""
+
+import os
+import logging
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List
+
+logger = logging.getLogger('dochan')
+
+
+@dataclass
+class BatchResult:
+    """단일 파일 처리 결과"""
+    file_path: str = ""
+    success: bool = False
+    output_path: str = ""
+    error_count: int = 0
+    errors: List[str] = field(default_factory=list)
+
+
+@dataclass
+class BatchSummary:
+    """배치 처리 전체 요약"""
+    total: int = 0
+    success: int = 0
+    failed: int = 0
+    results: List[BatchResult] = field(default_factory=list)
+
+    @property
+    def success_rate(self) -> float:
+        return self.success / max(self.total, 1) * 100
+
+
+def _process_single(file_path: str, output_dir: str, output_format: str) -> BatchResult:
+    """단일 파일 처리 (별도 프로세스에서 실행)"""
+    from .reader import Dochan
+
+    result = BatchResult(file_path=file_path)
+
+    try:
+        reader = Dochan(file_path)
+
+        # 출력 파일명 생성
+        base_name = os.path.splitext(os.path.basename(file_path))[0]
+        ext_map = {'markdown': '.md', 'json': '.json', 'text': '.txt'}
+        ext = ext_map.get(output_format, '.md')
+        output_path = os.path.join(output_dir, base_name + ext)
+
+        # 변환
+        if output_format == 'json':
+            content = reader.to_json()
+        elif output_format == 'text':
+            content = reader.to_plain_text()
+        else:
+            content = reader.to_markdown()
+
+        # 저장
+        with open(output_path, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+        result.success = True
+        result.output_path = output_path
+        result.errors = reader.errors
+        result.error_count = len(reader.errors)
+
+    except Exception as e:
+        result.success = False
+        result.errors = [str(e)]
+        result.error_count = 1
+
+    return result
+
+
+def batch_convert(
+    input_dir: str,
+    output_dir: str,
+    output_format: str = 'markdown',
+    max_workers: int = 4,
+    extensions: tuple = ('.hwp', '.hwpx'),
+) -> BatchSummary:
+    """
+    디렉토리 내 HWP 파일 일괄 변환
+
+    Args:
+        input_dir: 입력 디렉토리
+        output_dir: 출력 디렉토리
+        output_format: 'markdown', 'json', 'text'
+        max_workers: 병렬 워커 수
+        extensions: 처리할 확장자
+
+    Returns:
+        BatchSummary
+    """
+    # output_dir 경로 검증
+    try:
+        Path(output_dir).resolve().relative_to(Path(os.getcwd()).resolve())
+    except ValueError:
+        pass  # output_dir가 cwd 밖이어도 허용하되, 아래에서 symlink 공격 방지
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    # 파일 수집
+    files = []
+    resolved_input = Path(input_dir).resolve()
+    for root, _, filenames in os.walk(input_dir):
+        for fn in filenames:
+            if any(fn.lower().endswith(ext) for ext in extensions):
+                full_path = os.path.join(root, fn)
+                # Path traversal 방지: 실제 경로가 input_dir 내부인지 검증
+                try:
+                    Path(full_path).resolve().relative_to(resolved_input)
+                except ValueError:
+                    logger.warning(f"경로 이탈 감지, 건너뜀: {full_path}")
+                    continue
+                files.append(full_path)
+
+    summary = BatchSummary(total=len(files))
+    logger.info(f"배치 시작: {len(files)}개 파일, {max_workers} 워커")
+
+    # 병렬 처리
+    with ProcessPoolExecutor(max_workers=max_workers) as executor:
+        futures = {
+            executor.submit(_process_single, f, output_dir, output_format): f
+            for f in files
+        }
+
+        for future in as_completed(futures):
+            file_path = futures[future]
+            try:
+                result = future.result()
+                summary.results.append(result)
+                if result.success:
+                    summary.success += 1
+                    logger.info(f"✓ {os.path.basename(file_path)}")
+                else:
+                    summary.failed += 1
+                    logger.error(f"✗ {os.path.basename(file_path)}: {result.errors}")
+            except Exception as e:
+                summary.failed += 1
+                summary.results.append(BatchResult(
+                    file_path=file_path,
+                    success=False,
+                    errors=[str(e)],
+                    error_count=1,
+                ))
+                logger.error(f"✗ {os.path.basename(file_path)}: {e}")
+
+    logger.info(f"배치 완료: {summary.success}/{summary.total} 성공 ({summary.success_rate:.1f}%)")
+    return summary

dochan/cli.py

@@ -0,0 +1,118 @@
+"""dochan CLI — HWP/HWPX 문서를 터미널에서 변환
+
+사용법:
+  dochan convert 문서.hwp                    # → stdout에 Markdown
+  dochan convert 문서.hwp -o output.md       # → 파일로 저장
+  dochan convert 문서.hwp --format json      # → JSON 출력
+  dochan convert 문서.hwpx --format text     # → Plain text
+  dochan batch input_dir/ output_dir/        # → 디렉토리 일괄 변환
+  dochan info 문서.hwp                       # → 문서 메타데이터
+"""
+
+import argparse
+import sys
+import os
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='dochan',
+        description='dochan — 독한 HWP/HWPX 파서, AI/LLM 최적 Markdown 변환',
+    )
+    subparsers = parser.add_subparsers(dest='command', help='명령')
+
+    # convert
+    conv = subparsers.add_parser('convert', help='HWP/HWPX → Markdown/JSON/Text 변환')
+    conv.add_argument('file', help='HWP 또는 HWPX 파일 경로')
+    conv.add_argument('-o', '--output', default=None, help='출력 파일 경로 (기본: stdout)')
+    conv.add_argument('-f', '--format', choices=['markdown', 'json', 'text'],
+                      default='markdown', help='출력 형식 (기본: markdown)')
+    conv.add_argument('--ocr', action='store_true', help='이미지 OCR 활성화')
+
+    # batch
+    bat = subparsers.add_parser('batch', help='디렉토리 일괄 변환')
+    bat.add_argument('input_dir', help='입력 디렉토리')
+    bat.add_argument('output_dir', help='출력 디렉토리')
+    bat.add_argument('-f', '--format', choices=['markdown', 'json', 'text'],
+                     default='markdown', help='출력 형식')
+    bat.add_argument('-w', '--workers', type=int, default=4, help='병렬 워커 수')
+
+    # info
+    inf = subparsers.add_parser('info', help='문서 메타데이터 출력')
+    inf.add_argument('file', help='HWP 또는 HWPX 파일 경로')
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == 'convert':
+        _cmd_convert(args)
+    elif args.command == 'batch':
+        _cmd_batch(args)
+    elif args.command == 'info':
+        _cmd_info(args)
+
+
+def _cmd_convert(args):
+    from .reader import Dochan
+
+    if not os.path.exists(args.file):
+        print(f"에러: 파일을 찾을 수 없습니다: {args.file}", file=sys.stderr)
+        sys.exit(1)
+
+    doc = Dochan(args.file, ocr=args.ocr)
+
+    if args.format == 'json':
+        content = doc.to_json()
+    elif args.format == 'text':
+        content = doc.to_plain_text()
+    else:
+        content = doc.to_markdown()
+
+    if args.output:
+        with open(args.output, 'w', encoding='utf-8') as f:
+            f.write(content)
+        print(f"저장 완료: {args.output}", file=sys.stderr)
+    else:
+        print(content)
+
+    if doc.errors:
+        for err in doc.errors:
+            print(f"경고: {err}", file=sys.stderr)
+
+
+def _cmd_batch(args):
+    from .batch import batch_convert
+
+    if not os.path.isdir(args.input_dir):
+        print(f"에러: 디렉토리를 찾을 수 없습니다: {args.input_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    summary = batch_convert(
+        input_dir=args.input_dir,
+        output_dir=args.output_dir,
+        output_format=args.format,
+        max_workers=args.workers,
+    )
+    print(f"\n완료: {summary.success}/{summary.total} 성공 ({summary.success_rate:.1f}%)")
+
+
+def _cmd_info(args):
+    from .reader import Dochan
+    import json
+
+    if not os.path.exists(args.file):
+        print(f"에러: 파일을 찾을 수 없습니다: {args.file}", file=sys.stderr)
+        sys.exit(1)
+
+    doc = Dochan(args.file)
+    info = doc.metadata
+    info['file'] = args.file
+    info['format'] = 'hwpx' if args.file.lower().endswith('.hwpx') else 'hwp'
+    print(json.dumps(info, ensure_ascii=False, indent=2))
+
+
+if __name__ == '__main__':
+    main()

dochan/constants.py

@@ -0,0 +1,54 @@
+"""
+constants.py — 모든 TagID의 단일 진실 소스 (Single Source of Truth)
+기준: 한글문서파일형식_5.0_revision1.3.pdf
+"""
+
+HWPTAG_BEGIN = 16  # 0x010
+
+# ──── DocInfo 레코드 (스펙 표 13) ────
+HWPTAG_DOCUMENT_PROPERTIES  = 16   # BEGIN+0
+HWPTAG_ID_MAPPINGS          = 17   # BEGIN+1
+HWPTAG_BIN_DATA             = 18   # BEGIN+2
+HWPTAG_FACE_NAME            = 19   # BEGIN+3
+HWPTAG_BORDER_FILL          = 20   # BEGIN+4
+HWPTAG_CHAR_SHAPE           = 21   # BEGIN+5
+HWPTAG_TAB_DEF              = 22   # BEGIN+6
+HWPTAG_NUMBERING            = 23   # BEGIN+7
+HWPTAG_BULLET               = 24   # BEGIN+8
+HWPTAG_PARA_SHAPE           = 25   # BEGIN+9
+HWPTAG_STYLE                = 26   # BEGIN+10
+HWPTAG_DOC_DATA             = 27   # BEGIN+11
+HWPTAG_DISTRIBUTE_DOC_DATA  = 28   # BEGIN+12
+HWPTAG_COMPATIBLE_DOCUMENT  = 30   # BEGIN+14
+HWPTAG_LAYOUT_COMPATIBILITY = 31   # BEGIN+15
+
+# ──── BodyText 레코드 (스펙 표 57) ────
+HWPTAG_PARA_HEADER      = 66   # BEGIN+50
+HWPTAG_PARA_TEXT        = 67   # BEGIN+51
+HWPTAG_PARA_CHAR_SHAPE  = 68   # BEGIN+52
+HWPTAG_PARA_LINE_SEG    = 69   # BEGIN+53
+HWPTAG_PARA_RANGE_TAG   = 70   # BEGIN+54
+HWPTAG_CTRL_HEADER      = 71   # BEGIN+55
+HWPTAG_LIST_HEADER      = 72   # BEGIN+56
+HWPTAG_PAGE_DEF         = 73   # BEGIN+57
+HWPTAG_FOOTNOTE_SHAPE   = 74   # BEGIN+58
+HWPTAG_PAGE_BORDER_FILL = 75   # BEGIN+59
+HWPTAG_SHAPE_COMPONENT  = 76   # BEGIN+60
+HWPTAG_TABLE            = 77   # BEGIN+61
+HWPTAG_SHAPE_COMP_LINE      = 78   # BEGIN+62
+HWPTAG_SHAPE_COMP_RECT      = 79   # BEGIN+63
+HWPTAG_SHAPE_COMP_ELLIPSE   = 80   # BEGIN+64
+HWPTAG_SHAPE_COMP_ARC       = 81   # BEGIN+65
+HWPTAG_SHAPE_COMP_POLYGON   = 82   # BEGIN+66
+HWPTAG_SHAPE_COMP_CURVE     = 83   # BEGIN+67
+HWPTAG_SHAPE_COMP_OLE       = 84   # BEGIN+68
+HWPTAG_SHAPE_COMP_PICTURE   = 85   # BEGIN+69
+HWPTAG_SHAPE_COMP_CONTAINER = 86   # BEGIN+70
+HWPTAG_CTRL_DATA        = 87   # BEGIN+71
+HWPTAG_EQEDIT           = 88   # BEGIN+72
+HWPTAG_SHAPE_COMP_TEXTART   = 90   # BEGIN+74
+HWPTAG_FORM_OBJECT      = 91   # BEGIN+75
+HWPTAG_MEMO_SHAPE       = 92   # BEGIN+76
+HWPTAG_MEMO_LIST        = 93   # BEGIN+77
+HWPTAG_CHART_DATA       = 95   # BEGIN+79
+HWPTAG_VIDEO_DATA       = 98   # BEGIN+82

dochan/control_char.py

@@ -0,0 +1,51 @@
+"""
+control_char.py — 제어 문자별 WCHAR 단위 크기
+1 WCHAR = 2 bytes. 실제 바이트 크기 = 값 × 2
+스펙 표 6 (p.10-11) 기준
+"""
+
+CTRL_CHAR_WCHAR_SIZE = {
+    # ── char 타입 (1 WCHAR = 2 bytes) ──
+    10: 1,   # 줄바꿈 (line break)
+    13: 1,   # 문단 끝 (para break)
+    24: 1,   # 하이픈
+    25: 1, 26: 1, 27: 1, 28: 1, 29: 1,  # 예약 (char)
+    30: 1,   # 묶음 빈칸
+    31: 1,   # 고정폭 빈칸
+
+    # ── inline 타입 (8 WCHAR = 16 bytes) ──
+    4: 8,    # 필드 끝
+    5: 8, 6: 8, 7: 8,   # 예약 (inline)
+    8: 8,    # title mark
+    9: 8,    # 탭
+    19: 8, 20: 8,  # 예약 (inline)
+
+    # ── extended 타입 (8 WCHAR = 16 bytes) ──
+    1: 8,    # 예약
+    2: 8,    # 구역/단 정의
+    3: 8,    # 필드 시작
+    11: 8,   # 그리기 개체/표
+    12: 8,   # 예약
+    14: 8,   # 예약
+    15: 8,   # 숨은 설명
+    16: 8,   # 머리말/꼬리말
+    17: 8,   # 각주/미주
+    18: 8,   # 자동번호
+    21: 8,   # 페이지 컨트롤
+    22: 8,   # 책갈피/찾아보기
+    23: 8,   # 덧말/글자겹침
+}
+
+# extended 타입 ctrlId (이 코드의 컨트롤은 별도 오브젝트가 존재)
+EXTENDED_CTRL_CHARS = {1, 2, 3, 11, 12, 14, 15, 16, 17, 18, 21, 22, 23}
+
+
+def get_advance_bytes(char_code: int) -> int:
+    """제어 문자 하나가 차지하는 바이트 수 반환"""
+    wchar_count = CTRL_CHAR_WCHAR_SIZE.get(char_code, 1)
+    return wchar_count * 2
+
+
+def is_extended_ctrl(char_code: int) -> bool:
+    """별도 오브젝트(표, 그림 등)를 가리키는 확장 컨트롤인지"""
+    return char_code in EXTENDED_CTRL_CHARS

dochan/fallback/filter_server.py

@@ -0,0 +1,93 @@
+"""
+fallback/filter_server.py — 웹한글 기안기 필터 서버 연동
+파싱 실패 시 폴백으로 사용하거나, GT(Ground Truth) 비교용
+
+필터 서버 API:
+  POST /convert — HWP → HTML/PDF 변환 요청
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+logger = logging.getLogger('dochan')
+
+
+@dataclass
+class FilterServerConfig:
+    """필터 서버 연결 설정"""
+    base_url: str = "http://localhost:8080"
+    timeout: int = 30
+    api_key: str = ""
+
+
+class FilterServerClient:
+    """웹한글 기안기 필터 서버 클라이언트"""
+
+    def __init__(self, config: Optional[FilterServerConfig] = None):
+        self.config = config or FilterServerConfig()
+        self._available = None
+
+    def is_available(self) -> bool:
+        """필터 서버 접속 가능 여부"""
+        if self._available is not None:
+            return self._available
+
+        try:
+            import urllib.request
+            req = urllib.request.Request(
+                f"{self.config.base_url}/health",
+                method='GET',
+            )
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                self._available = resp.status == 200
+        except Exception:
+            self._available = False
+
+        return self._available
+
+    def convert_to_html(self, hwp_path: str) -> Optional[str]:
+        """HWP → HTML 변환 (필터 서버 사용)"""
+        if not self.is_available():
+            logger.warning("필터 서버 사용 불가")
+            return None
+
+        try:
+            import urllib.request
+
+            with open(hwp_path, 'rb') as f:
+                file_data = f.read()
+
+            # multipart/form-data 전송
+            boundary = '----HWPParserBoundary'
+            filename = hwp_path.split('/')[-1]
+
+            body = (
+                f'--{boundary}\r\n'
+                f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n'
+                f'Content-Type: application/octet-stream\r\n\r\n'
+            ).encode('utf-8') + file_data + f'\r\n--{boundary}--\r\n'.encode('utf-8')
+
+            req = urllib.request.Request(
+                f"{self.config.base_url}/convert",
+                data=body,
+                headers={
+                    'Content-Type': f'multipart/form-data; boundary={boundary}',
+                },
+                method='POST',
+            )
+
+            if self.config.api_key:
+                req.add_header('Authorization', f'Bearer {self.config.api_key}')
+
+            with urllib.request.urlopen(req, timeout=self.config.timeout) as resp:
+                return resp.read().decode('utf-8')
+
+        except Exception as e:
+            logger.error(f"필터 서버 변환 실패: {e}")
+            return None
+
+    def convert_as_fallback(self, hwp_path: str, original_errors: list) -> Optional[str]:
+        """파싱 실패 시 폴백 변환"""
+        logger.info(f"자체 파싱 실패 ({len(original_errors)}건 에러) → 필터 서버 폴백 시도")
+        return self.convert_to_html(hwp_path)

dochan/hwp/bin_data.py

@@ -0,0 +1,96 @@
+"""
+hwp/bin_data.py — BinData 이미지 연결
+OLE 스토리지의 BinData/ 하위에 저장된 바이너리 데이터를 추출
+"""
+
+import logging
+import struct
+import olefile
+from dataclasses import dataclass
+from typing import Dict, Optional
+
+from ..utils.safe_decompress import safe_zlib_decompress
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BinDataItem:
+    """추출된 바이너리 데이터"""
+    storage_id: int = 0
+    data: bytes = b""
+    extension: str = ""
+
+    @property
+    def filename(self) -> str:
+        return f"BIN{self.storage_id:04X}.{self.extension}" if self.extension else f"BIN{self.storage_id:04X}"
+
+
+def extract_bin_data(ole: olefile.OleFileIO, is_compressed: bool) -> Dict[int, BinDataItem]:
+    """
+    OLE 스토리지에서 BinData/ 하위의 모든 바이너리 데이터 추출
+
+    반환: {storage_id: BinDataItem} 딕셔너리
+    """
+    result = {}
+
+    for entry in ole.listdir():
+        if len(entry) >= 2 and entry[0] == 'BinData':
+            storage_name = entry[1]  # 예: "BIN0001.bmp"
+
+            try:
+                # 스토리지 ID 추출 (BIN 접두어 제거, 16진수)
+                base_name = storage_name.split('.')[0]
+                if base_name.upper().startswith('BIN'):
+                    storage_id = int(base_name[3:], 16)
+                else:
+                    continue
+
+                # 확장자
+                ext = storage_name.split('.')[-1] if '.' in storage_name else ""
+
+                # 데이터 읽기
+                raw_data = ole.openstream('/'.join(entry)).read()
+
+                # 압축 해제 (문서가 압축 설정인 경우)
+                if is_compressed:
+                    try:
+                        raw_data = safe_zlib_decompress(raw_data)
+                    except (ValueError, Exception) as e:
+                        logger.debug("BinData 압축 해제 실패 (비압축 데이터일 수 있음): %s", e)
+
+                result[storage_id] = BinDataItem(
+                    storage_id=storage_id,
+                    data=raw_data,
+                    extension=ext.lower(),
+                )
+
+            except (ValueError, struct.error, UnicodeDecodeError, OSError) as e:
+                logger.warning("BinData 항목 '%s' 파싱 실패: %s", storage_name, e)
+                continue
+
+    return result
+
+
+def link_images_to_bin_data(doc, bin_data_items: Dict[int, BinDataItem],
+                            bin_data_entries: list):
+    """
+    Document 내 Image 객체에 실제 바이너리 데이터 연결
+
+    bin_data_entries: DocInfo에서 파싱한 BinDataEntry 목록
+    bin_data_items: OLE에서 추출한 BinDataItem 딕셔너리
+    """
+    from ..model.image import Image
+
+    for section in doc.sections:
+        for elem in section.elements:
+            if isinstance(elem, Image) and elem.bin_id >= 0:
+                # bin_id는 DocInfo의 BinDataEntry 인덱스 (0-based)
+                if elem.bin_id < len(bin_data_entries):
+                    entry = bin_data_entries[elem.bin_id]
+                    storage_id = entry.bin_data_id
+
+                    if storage_id in bin_data_items:
+                        item = bin_data_items[storage_id]
+                        elem.image_data = item.data
+                        elem.filename = item.filename