extract-hwp 0.1.0__tar.gz

extract_hwp-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# UV
+uv.lock

extract_hwp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

extract_hwp-0.1.0/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Python library for extracting text from Korean HWP (Hangul Word Processor) files, supporting both HWP 5.0 (OLE format) and HWPX (ZIP-based XML format) files. The project includes password protection detection and structured text extraction capabilities.
+
+## Development Commands
+
+### Package Management
+- **Install dependencies**: `uv sync` (uses uv for dependency management)
+- **Run main script**: `python main.py` (basic hello world entry point)
+- **Run extraction**: `python -m extract_hwp` or import functions from `extract_hwp.py`
+
+### Testing and Quality
+No specific test commands are configured yet - tests would need to be added to pyproject.toml.
+
+## Code Architecture
+
+### Core Components
+
+**extract_hwp.py**: Main extraction module with three key functions:
+- `extract_text_from_hwp()`: Unified interface that routes to appropriate extractor based on file extension
+- `extract_text_from_hwpx()`: HWPX file processor (ZIP-based XML format)
+- `extract_text_from_hwp5()`: HWP 5.0 processor (OLE compound document format)
+
+**Password Protection Detection**:
+- `is_hwpx_password_protected()`: Checks HWPX files via META-INF/manifest.xml encryption data
+- `is_hwp5_password_protected()`: Checks HWP 5.0 files via FileHeader stream bit flags
+- `is_hwp_file_password_protected()`: Unified interface for both formats
+
+### File Format Handling
+
+**HWPX Files**: 
+- ZIP archives containing XML sections in `Contents/section*.xml`
+- Text extracted from `<p>` (paragraph) elements containing `<t>` (text) nodes
+- Preserves paragraph structure with newlines
+
+**HWP 5.0 Files**:
+- OLE compound documents with compressed BodyText streams
+- Requires decompression (zlib) and binary parsing of structured records
+- Text stored in PARA_TEXT records (tag_id: 67) as Unicode sequences
+- Supports multiple sections (`BodyText/Section0`, `BodyText/Section1`, etc.)
+
+### Dependencies
+
+**External Libraries**:
+- `olefile`: OLE compound document parsing for HWP 5.0 files
+- `superclaude>=3.0.0.2`: Framework dependency (external utility framework)
+
+**Framework Integration**:
+The code imports from `core.util_text` and `core.util_extraction` modules, indicating this is part of a larger text extraction framework. These modules provide:
+- Text cleaning/indexing utilities
+- Error handling decorators (@handle_extraction_errors)
+- File validation and logging utilities
+
+### Error Handling Strategy
+
+The codebase uses a defensive approach:
+- Password-protected files are detected and skipped (not extracted)
+- File validation occurs before processing
+- Graceful degradation for parsing errors
+- Comprehensive logging for troubleshooting
+- Returns empty strings rather than throwing exceptions for most extraction failures
+
+### Character Encoding Considerations
+
+HWP 5.0 extraction includes specific Unicode range validation:
+- Basic Latin (0x0020-0x007E)
+- Korean syllables (0xAC00-0xD7AF) 
+- Korean Jamo (0x3130-0x318F)
+- Full-width characters (0xFF00-0xFFEF)
+- General punctuation (0x2000-0x206F)

extract_hwp-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, thlee
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

extract_hwp-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: extract-hwp
+Version: 0.1.0
+Summary: Python library for extracting text from Korean HWP files (HWP 5.0 and HWPX formats)
+Project-URL: Homepage, https://github.com/thlee/extract-hwp
+Project-URL: Bug Reports, https://github.com/thlee/extract-hwp/issues
+Project-URL: Source, https://github.com/thlee/extract-hwp
+Author-email: extract-hwp <extract-hwp@example.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: document,hwp,hwpx,korean,text-extraction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.8
+Requires-Dist: olefile>=0.46
+Description-Content-Type: text/markdown
+
+# extract-hwp
+
+한글과컴퓨터의 HWP 파일(HWP 5.0 및 HWPX 형식)에서 텍스트를 추출하는 Python 라이브러리입니다.
+
+## 특징
+
+- **다중 포맷 지원**: HWP 5.0 (OLE) 및 HWPX (ZIP/XML) 파일 모두 지원
+- **암호화 파일 감지**: 처리하기 전에 암호로 보호된 파일을 감지
+- **구조화된 추출**: 텍스트 추출 시 단락 구조 보존
+- **견고한 오류 처리**: 손상되거나 잘못된 파일에 대한 방어적 처리
+- **유니코드 지원**: 한글 및 다국어 텍스트 완전 지원
+
+## 설치
+
+```bash
+pip install extract-hwp
+```
+
+## 사용법
+
+### 기본 사용법
+
+```python
+from extract_hwp import extract_text_from_hwp
+
+# HWP 또는 HWPX 파일에서 텍스트 추출
+text, error = extract_text_from_hwp("document.hwp")
+if error is None:
+    print(text)
+else:
+    print(f"오류: {error}")
+```
+
+### 포맷별 추출
+
+```python
+from extract_hwp import extract_text_from_hwpx, extract_text_from_hwp5
+
+# HWPX 파일 전용
+hwpx_text = extract_text_from_hwpx("document.hwpx")
+
+# HWP 5.0 파일 전용
+hwp5_text = extract_text_from_hwp5("document.hwp")
+```
+
+### 암호화 파일 감지
+
+```python
+from extract_hwp import is_hwp_file_password_protected
+
+if is_hwp_file_password_protected("document.hwp"):
+    print("파일이 암호로 보호되어 있습니다.")
+else:
+    text, error = extract_text_from_hwp("document.hwp")
+```
+
+## API 참조
+
+### 핵심 함수
+
+#### `extract_text_from_hwp(filepath)`
+
+HWP/HWPX 파일에서 텍스트를 추출합니다 (통합 인터페이스).
+
+**매개변수:**
+- `filepath` (str): HWP 또는 HWPX 파일 경로
+
+**반환값:**
+- `tuple`: (추출된_텍스트, 오류_메시지). 성공시 오류_메시지는 None
+
+**예외:**
+- `FileNotFoundError`: 파일을 찾을 수 없음
+- `PermissionError`: 파일 접근 권한이 없음
+- `ValueError`: 지원하지 않는 파일 형식
+
+### 포맷별 함수
+
+#### `extract_text_from_hwpx(hwpx_file_path)`
+
+HWPX 파일에서 텍스트를 추출합니다.
+
+**매개변수:**
+- `hwpx_file_path` (str): HWPX 파일 경로
+
+**반환값:**
+- `str`: 추출된 텍스트 (오류 시 빈 문자열)
+
+#### `extract_text_from_hwp5(filepath)`
+
+HWP 5.0 (OLE) 파일에서 텍스트를 추출합니다.
+
+**매개변수:**
+- `filepath` (str): HWP 파일 경로
+
+**반환값:**
+- `str`: 추출된 텍스트 (오류 시 빈 문자열)
+
+### 암호화 감지 함수
+
+#### `is_hwp_file_password_protected(filepath)`
+
+HWP/HWPX 파일이 암호로 보호되어 있는지 확인합니다.
+
+**매개변수:**
+- `filepath` (str): 확인할 파일 경로
+
+**반환값:**
+- `bool`: 암호로 보호된 경우 True, 그렇지 않으면 False
+
+## 지원 포맷
+
+### HWP 5.0 (OLE 포맷)
+- 확장자: `.hwp`
+- 구조: OLE 복합 문서 형식
+- 압축: zlib 압축 지원
+- 특징: 바이너리 구조 분석을 통한 텍스트 추출
+
+### HWPX (ZIP/XML 포맷)
+- 확장자: `.hwpx`
+- 구조: XML 문서가 포함된 ZIP 아카이브
+- 특징: 구조화된 텍스트 추출을 위한 XML 파싱
+
+## 의존성
+
+- `olefile>=0.46`: HWP 5.0 OLE 파일 처리
+
+## 개발
+
+### 개발 환경 설정
+
+```bash
+# 저장소 복제
+git clone https://github.com/thlee/extract-hwp.git
+cd extract-hwp
+
+# 의존성 설치
+uv sync
+
+# 개발 의존성 포함 설치
+uv sync --extra dev
+```
+
+### 테스트
+
+```bash
+# 테스트 실행
+pytest
+
+# 커버리지 포함
+pytest --cov=src/extract_hwp
+```
+
+### 코드 품질
+
+```bash
+# 코드 포맷팅
+black src/ tests/
+
+# 타입 검사
+mypy src/
+```
+
+## 라이선스
+
+BSD 3-Clause License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.
+
+## 변경사항
+
+버전 히스토리는 [CHANGELOG.md](CHANGELOG.md)에서 확인할 수 있습니다.

extract_hwp-0.1.0/README.md

@@ -0,0 +1,169 @@
+# extract-hwp
+
+한글과컴퓨터의 HWP 파일(HWP 5.0 및 HWPX 형식)에서 텍스트를 추출하는 Python 라이브러리입니다.
+
+## 특징
+
+- **다중 포맷 지원**: HWP 5.0 (OLE) 및 HWPX (ZIP/XML) 파일 모두 지원
+- **암호화 파일 감지**: 처리하기 전에 암호로 보호된 파일을 감지
+- **구조화된 추출**: 텍스트 추출 시 단락 구조 보존
+- **견고한 오류 처리**: 손상되거나 잘못된 파일에 대한 방어적 처리
+- **유니코드 지원**: 한글 및 다국어 텍스트 완전 지원
+
+## 설치
+
+```bash
+pip install extract-hwp
+```
+
+## 사용법
+
+### 기본 사용법
+
+```python
+from extract_hwp import extract_text_from_hwp
+
+# HWP 또는 HWPX 파일에서 텍스트 추출
+text, error = extract_text_from_hwp("document.hwp")
+if error is None:
+    print(text)
+else:
+    print(f"오류: {error}")
+```
+
+### 포맷별 추출
+
+```python
+from extract_hwp import extract_text_from_hwpx, extract_text_from_hwp5
+
+# HWPX 파일 전용
+hwpx_text = extract_text_from_hwpx("document.hwpx")
+
+# HWP 5.0 파일 전용
+hwp5_text = extract_text_from_hwp5("document.hwp")
+```
+
+### 암호화 파일 감지
+
+```python
+from extract_hwp import is_hwp_file_password_protected
+
+if is_hwp_file_password_protected("document.hwp"):
+    print("파일이 암호로 보호되어 있습니다.")
+else:
+    text, error = extract_text_from_hwp("document.hwp")
+```
+
+## API 참조
+
+### 핵심 함수
+
+#### `extract_text_from_hwp(filepath)`
+
+HWP/HWPX 파일에서 텍스트를 추출합니다 (통합 인터페이스).
+
+**매개변수:**
+- `filepath` (str): HWP 또는 HWPX 파일 경로
+
+**반환값:**
+- `tuple`: (추출된_텍스트, 오류_메시지). 성공시 오류_메시지는 None
+
+**예외:**
+- `FileNotFoundError`: 파일을 찾을 수 없음
+- `PermissionError`: 파일 접근 권한이 없음
+- `ValueError`: 지원하지 않는 파일 형식
+
+### 포맷별 함수
+
+#### `extract_text_from_hwpx(hwpx_file_path)`
+
+HWPX 파일에서 텍스트를 추출합니다.
+
+**매개변수:**
+- `hwpx_file_path` (str): HWPX 파일 경로
+
+**반환값:**
+- `str`: 추출된 텍스트 (오류 시 빈 문자열)
+
+#### `extract_text_from_hwp5(filepath)`
+
+HWP 5.0 (OLE) 파일에서 텍스트를 추출합니다.
+
+**매개변수:**
+- `filepath` (str): HWP 파일 경로
+
+**반환값:**
+- `str`: 추출된 텍스트 (오류 시 빈 문자열)
+
+### 암호화 감지 함수
+
+#### `is_hwp_file_password_protected(filepath)`
+
+HWP/HWPX 파일이 암호로 보호되어 있는지 확인합니다.
+
+**매개변수:**
+- `filepath` (str): 확인할 파일 경로
+
+**반환값:**
+- `bool`: 암호로 보호된 경우 True, 그렇지 않으면 False
+
+## 지원 포맷
+
+### HWP 5.0 (OLE 포맷)
+- 확장자: `.hwp`
+- 구조: OLE 복합 문서 형식
+- 압축: zlib 압축 지원
+- 특징: 바이너리 구조 분석을 통한 텍스트 추출
+
+### HWPX (ZIP/XML 포맷)
+- 확장자: `.hwpx`
+- 구조: XML 문서가 포함된 ZIP 아카이브
+- 특징: 구조화된 텍스트 추출을 위한 XML 파싱
+
+## 의존성
+
+- `olefile>=0.46`: HWP 5.0 OLE 파일 처리
+
+## 개발
+
+### 개발 환경 설정
+
+```bash
+# 저장소 복제
+git clone https://github.com/thlee/extract-hwp.git
+cd extract-hwp
+
+# 의존성 설치
+uv sync
+
+# 개발 의존성 포함 설치
+uv sync --extra dev
+```
+
+### 테스트
+
+```bash
+# 테스트 실행
+pytest
+
+# 커버리지 포함
+pytest --cov=src/extract_hwp
+```
+
+### 코드 품질
+
+```bash
+# 코드 포맷팅
+black src/ tests/
+
+# 타입 검사
+mypy src/
+```
+
+## 라이선스
+
+BSD 3-Clause License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.
+
+## 변경사항
+
+버전 히스토리는 [CHANGELOG.md](CHANGELOG.md)에서 확인할 수 있습니다.

extract_hwp-0.1.0/examples/README.md

@@ -0,0 +1,174 @@
+# extract-hwp 사용 예제
+
+이 디렉토리에는 extract-hwp 라이브러리를 사용하는 다양한 예제들이 포함되어 있습니다.
+
+## 예제 파일들
+
+### 1. `basic_usage.py` - 기본 사용법
+라이브러리의 기본적인 사용 방법을 보여주는 예제입니다.
+
+```bash
+python basic_usage.py
+```
+
+**주요 기능:**
+- 단일 파일 텍스트 추출
+- 암호화 파일 감지
+- 오류 처리 방법
+- 포맷별 추출 함수 사용법
+
+### 2. `batch_processing.py` - 일괄 처리
+디렉토리 내의 모든 HWP 파일을 일괄 처리하는 예제입니다.
+
+```bash
+python batch_processing.py <디렉토리> [출력형식]
+```
+
+**사용 예제:**
+```bash
+# 현재 디렉토리의 모든 HWP 파일을 텍스트 파일로 저장
+python batch_processing.py ./documents txt
+
+# JSON 형식으로 결과 저장
+python batch_processing.py ./documents json
+```
+
+**주요 기능:**
+- 재귀적 파일 검색 (하위 디렉토리 포함)
+- 일괄 처리 진행 상황 표시
+- 처리 결과 통계
+- 다양한 출력 형식 지원
+
+### 3. `cli_tool.py` - 명령줄 도구
+HWP 파일 처리를 위한 완전한 명령줄 인터페이스입니다.
+
+```bash
+python cli_tool.py <파일경로> [옵션]
+```
+
+**사용 예제:**
+```bash
+# 기본 사용 (표준 출력)
+python cli_tool.py document.hwp
+
+# 파일로 저장
+python cli_tool.py document.hwp --output extracted.txt
+
+# 암호화 여부만 확인
+python cli_tool.py document.hwp --check-password
+
+# 조용한 모드로 실행
+python cli_tool.py document.hwpx --quiet --output-dir ./outputs
+```
+
+**주요 옵션:**
+- `-o, --output`: 출력 파일 지정
+- `--output-dir`: 출력 디렉토리 지정
+- `-c, --check-password`: 암호화 여부만 확인
+- `-q, --quiet`: 진행 메시지 숨기기
+- `--encoding`: 출력 파일 인코딩 지정
+
+## 실행 방법
+
+### 개발 환경에서 실행
+```bash
+# extract-hwp 프로젝트 루트 디렉토리에서
+cd examples
+python basic_usage.py
+python batch_processing.py ./test_files
+python cli_tool.py test.hwp
+```
+
+### 설치된 패키지로 실행
+패키지가 설치된 상태에서는 import 경로 수정이 필요합니다:
+
+```python
+# 예제 파일 상단의 다음 부분을 제거하거나 주석 처리
+# sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+```
+
+## 테스트 파일 준비
+
+예제를 실제로 테스트해보려면 HWP/HWPX 파일이 필요합니다:
+
+1. **샘플 파일 생성**: 한글(HWP)에서 간단한 문서를 작성하고 `.hwp` 및 `.hwpx` 형식으로 저장
+2. **테스트 디렉토리**: `./test_files/` 디렉토리를 만들고 샘플 파일들을 넣기
+3. **암호화 파일**: 암호가 설정된 HWP 파일도 테스트용으로 준비
+
+## 고급 사용법
+
+### 커스텀 처리 로직
+```python
+from extract_hwp import extract_text_from_hwp, is_hwp_file_password_protected
+
+def custom_processor(file_path):
+    """커스텀 HWP 파일 처리기"""
+    
+    # 1. 암호화 확인
+    if is_hwp_file_password_protected(file_path):
+        return None, "암호화된 파일"
+    
+    # 2. 텍스트 추출
+    text, error = extract_text_from_hwp(file_path)
+    if error:
+        return None, error
+    
+    # 3. 후처리 (예: 텍스트 정리)
+    processed_text = text.strip()
+    processed_text = '\n'.join(line.strip() for line in processed_text.split('\n') if line.strip())
+    
+    return processed_text, None
+```
+
+### 에러 처리 패턴
+```python
+import logging
+
+def safe_extract(file_path):
+    """안전한 텍스트 추출 (로깅 포함)"""
+    try:
+        text, error = extract_text_from_hwp(file_path)
+        if error:
+            logging.warning(f"추출 실패: {file_path} - {error}")
+            return ""
+        
+        logging.info(f"추출 성공: {file_path} ({len(text)} 문자)")
+        return text
+        
+    except Exception as e:
+        logging.error(f"예외 발생: {file_path} - {e}")
+        return ""
+```
+
+## 성능 최적화 팁
+
+1. **대용량 파일**: 매우 큰 HWP 파일의 경우 메모리 사용량에 주의
+2. **일괄 처리**: 많은 파일을 처리할 때는 멀티프로세싱 사용 고려
+3. **암호화 확인**: 처리 전에 암호화 여부를 먼저 확인하여 불필요한 처리 방지
+
+## 문제 해결
+
+### 일반적인 문제들
+
+1. **ImportError**: 패키지가 설치되지 않은 경우
+   ```bash
+   pip install extract-hwp
+   ```
+
+2. **파일을 찾을 수 없음**: 파일 경로 확인
+   ```python
+   import os
+   print(os.path.exists("your_file.hwp"))
+   ```
+
+3. **인코딩 오류**: 파일명에 특수문자가 있는 경우
+   ```python
+   file_path = file_path.encode('utf-8').decode('utf-8')
+   ```
+
+4. **권한 오류**: 파일 읽기 권한 확인
+   ```bash
+   ls -la your_file.hwp
+   ```
+
+더 자세한 정보는 프로젝트의 메인 README.md를 참조하세요.