Metadata-Version: 2.5
Name: extract-hwp
Version: 0.2.1
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
```

GitHub의 최신 코드를 설치하려면 다음 명령을 사용합니다. PyPI에 배포된 버전은
저장소의 버전과 다를 수 있습니다.

```bash
pip install "extract-hwp @ git+https://github.com/thlee/extract-hwp.git"
```

## 사용법

### 기본 사용법

```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`: 파일을 찾을 수 없음

그 밖의 처리 오류와 지원하지 않는 확장자는 `("", 오류 메시지)`로 반환합니다.

### 포맷별 함수

#### `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`: 추출된 텍스트 (오류 시 빈 문자열)

### 읽기 한도와 오류 처리

통합 함수는 손상된 문서나 읽기 한도 초과를 오류 메시지로 반환합니다.
포맷별 추출 함수는 일반적인 형식 오류 시 빈 문자열을 반환하지만,
한도 초과 시에는 패키지에서 제공하는 `HwpReadLimitError`를 발생시킵니다.
HWP/HWPX 암호 확인 함수도 헤더 또는 manifest 읽기 한도 초과 시 같은 예외를
발생시킵니다.

| 대상 | 압축 해제 한도 |
| --- | --- |
| HWP 본문 전체 | 128 MiB |
| HWP `DocInfo` (저장 크기 및 압축 해제 크기 각각) | 64 MiB |
| HWPX 개별 XML (`content.hpf`, 암호 확인 manifest 포함) | 64 MiB |
| HWPX 본문 구역 및 `content.hpf` 합계 | 256 MiB |

암호 확인 manifest는 별도로 제한합니다. 읽지 않는 이미지·첨부파일은 XML 합계에
포함하지 않습니다. 이 한도는 프로세스 전체 메모리 사용량의 상한은 아닙니다.

암호·배포용·DRM 보호 HWP는 복호화하지 않으며 본문 추출 대상에서 제외합니다.
통합 함수는 암호화된 HWPX도 감지하여 제외합니다.

HWP `FileHeader`는 스트림을 열기 전에 규격 크기인 256바이트인지 검사합니다.
`DocInfo`에 선언된 구역 수와 실제 본문 구역이 일치해야 성공으로 처리합니다.
필수 `DocInfo`가 누락되거나 손상된 파일은 추출에 실패하지만, 선택 사항인
요약 정보 스트림이 없는 파일은 처리할 수 있습니다. 전자서명 관련 비트만
설정된 문서는 차단하지 않으며, 서명의 유효성을 검증하는 기능은 제공하지 않습니다.

### 암호화 감지 함수

#### `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 --group dev
```

### 테스트

```bash
# 테스트 실행
uv run pytest
```

테스트는 합성 OLE 스트림·실제 ZIP/XML 및 저장소에 포함된 예제 파일을 사용합니다.
DocChaJa 설치나 검색 엔진 의존성이 필요하지 않습니다.

### 패키지 빌드

```bash
uv build
uv run twine check dist/*
```

## 라이선스

BSD 3-Clause License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

## 변경사항

버전 히스토리는 [CHANGELOG.md](CHANGELOG.md)에서 확인할 수 있습니다.
