자주 묻는 질문 (FAQ)

`ModuleNotFoundError: No module named 'hwpx'` 오류가 발생합니다.

PyPI에서 설치했다면 가상 환경을 활성화하고 pip install python-hwpx만 실행해도 됩니다. 저장소를 직접 클론해 개발 중이라면 루트 src 디렉터리를 PYTHONPATH에 추가해야 합니다. 다음 명령을 참고하세요.

export PYTHONPATH="$(pwd)/src:${PYTHONPATH}"

PowerShell을 사용한다면:

$env:PYTHONPATH = "$(Get-Location)\src;" + $env:PYTHONPATH

보다 자세한 절차는 설치 가이드를 참고하세요.

`HwpxStructureError` 예외가 발생하는 이유는 무엇인가요?

HwpxStructureError는 패키지 내 필수 파일이 누락되거나 META-INF/container.xml에 선언된 루트 파일을 찾지 못했을 때 발생합니다. 문제가 되는 HWPX 파일이 규격을 따르는지 다음 항목을 확인하세요.

ZIP 루트에 mimetype 파일이 존재하며 내용이 application/hwp+zip인지 확인합니다.
META-INF/container.xml에 선언된 경로가 실제 파트와 일치하는지 검사합니다.
version.xml이 포함되어 있고, Contents/ 디렉터리에 문서 본문(section*.xml)이 있는지 확인합니다.

파일이 손상되었다면 Hancom Office에서 다시 저장하거나, HwpxPackage.open() 호출 시 예외를 잡아 사용자에게 오류를 알리면 됩니다.

`hwpx.package.HwpxPackage`와 `hwpx.opc.package.HwpxPackage`의 차이는 무엇인가요?

두 클래스 모두 HWPX 패키지를 나타내지만 역할이 다릅니다.

hwpx.opc.package.HwpxPackage는 OPC 구조 검증과 파트 로딩에 초점을 맞춘 저수준 컨테이너입니다.
hwpx.package.HwpxPackage는 HwpxDocument가 사용하는 상위 래퍼로, 수정된 XML 파트를 직렬화하고 저장하는 기능을 제공합니다.

패키지를 직접 다룰 때는 일반적으로 hwpx.opc.package.HwpxPackage를 사용하고, 문서 편집 API와 함께 작업할 때는 HwpxDocument.package 속성으로 제공되는 고수준 패키지를 사용하세요.

파일을 메모리 버퍼나 HTTP 응답으로부터 열 수 있나요?

네. HwpxPackage.open()과 HwpxDocument.open()은 파일 경로뿐 아니라 바이트열과 파일 객체도 지원합니다.

from io import BytesIO
from hwpx import HwpxDocument

with open("sample.hwpx", "rb") as fp:
    data = fp.read()

document = HwpxDocument.open(BytesIO(data))
print(len(document.paragraphs))

수정된 결과를 바이트로 받고 싶다면 document.save() 호출 시 경로를 생략하면 됩니다.

중첩 문단을 제외하거나 특정 섹션만 순회하려면 어떻게 해야 하나요?

TextExtractor.iter_document_paragraphs(include_nested=False)를 호출하면 표/컨트롤 내부 문단을 건너뛸 수 있습니다. 섹션별로 처리하려면 iter_sections() 결과를 필터링한 뒤 iter_paragraphs()를 호출하세요.

from hwpx.tools.text_extractor import TextExtractor

with TextExtractor("sample.hwpx") as extractor:
    for section in extractor.iter_sections():
        if section.index != 0:
            continue
        for paragraph in extractor.iter_paragraphs(section, include_nested=False):
            print(section.name, paragraph.index, paragraph.text())

저장 시 원본 파일을 덮어쓰지 않고 새 파일로 만들고 싶습니다.

HwpxDocument.save("output.hwpx")처럼 경로를 지정하면 해당 경로로 새 ZIP 아카이브가 생성됩니다. 이미 열린 파일 객체나 BytesIO 버퍼를 전달해도 되며, 반환값으로 새 경로 또는 버퍼가 제공됩니다.