결과·경고·오류
결과 객체 세 가지
값을 만들어 내는 연산은 값과 보고서를 한 객체로 돌려줍니다. 셋 다 frozen dataclass입니다.
| 타입 | 필드 | 돌려주는 연산 |
|---|---|---|
DocumentResult[R] | document: Document, report: R | fill·set_cell·patch·insert_para·delete_para·stamp·restyle, convert_md·from_json·convert_hwp5 |
TextResult[R] | text: str, report: R | to_json·export_section·to_md |
BytesResult[R] | data: bytes, report: R | to_pdf |
검사 연산(inspect·outline·fields·validate·read·diff·stamp_plan)과 templates·schema는 보고서 dict만 돌려줍니다.
import hwpforge
result = hwpforge.convert_md("# 제목\n\n본문")
result.document # Document
result.report # {'sections': 1, 'paragraphs': ..., 'assets': [], 'warnings': []}
document, report = result.document, result.report # 필드 이름으로 풀어 쓰는 편이 안전합니다
보고서와 타입 힌트
보고서는 TypedDict입니다. 키 이름은 연산 계층의 보고서 구조체 필드명과 같고, hwpforge._hwpforge 스텁(_hwpforge.pyi)에 전부 선언돼 있습니다. 편집기에서 자동 완성과 타입 검사를 받으려면 그 이름을 가져오세요(스텁 모듈 자체는 비공개이지만 타입 이름은 안정적인 편입니다).
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from hwpforge._hwpforge import FillReport, InspectReport
def summarize(report: "InspectReport") -> str:
return f"{report['sections']} sections, {report['paragraphs']} paragraphs"
NotRequired로 선언된 키(예: InspectReport["styles"], StampReport["manifest"], 경고의 hint)는 없을 수 있으니 .get()으로 읽으세요. 그 밖의 키는 항상 있고, 값이 없으면 None입니다.
warnings — 조용한 손실을 드러내는 채널
templates()·schema()를 뺀 모든 보고서에 warnings: list[{code, message, hint?}]가 있습니다. 실패가 아니라 “성공했지만 이것은 보존되지 않았다“는 신호이므로, 저장하기 전에 읽는 습관이 필요합니다.
doc = hwpforge.Document.open("hancom.hwpx")
rebuilt = hwpforge.from_json(doc.to_json().text, base=doc)
for warning in rebuilt.report["warnings"]:
print(warning["code"], "-", warning["message"])
if warning.get("hint"):
print(" →", warning["hint"])
# LAYOUT_CACHE_DROPPED - ...
자주 보게 되는 코드:
| 코드 | 뜻 | 어디서 |
|---|---|---|
LAYOUT_CACHE_DROPPED | 입력 해석이나 재인코드에서 줄 조판 캐시를 담지 못했다(최종 원문 캐시 잔존 여부와 구별하며, 보존 편집의 계획적 삭제는 이 경고를 만들지 않음) — 한컴에서 다시 저장하면 복원 | from_json·restyle 등 재인코드 경로, convert_hwp5 |
IMAGE_EMBED_SKIPPED | Markdown의 이미지를 읽지 못해 뺐다(base_dir 없음, 경로 밖, 미지원 형식) | convert_md |
CONTAINER_TOO_DEEP | Markdown 보기(to_md lossy·styled)가 너무 깊이 중첩된 내용을 그리지 않고 표기((중첩 표 생략) 등)로 바꿨다 — lossy 는 표 안 표 8 단계, styled 는 컨테이너 32 겹이 한도 | to_md |
EQUATION_AS_TEXT | styled Markdown 보기가 수식의 LaTeX를 Markdown에 안전하게 쓸 수 없어($·]( 를 담거나 \ 로 끝남) 수식 스크립트를 일반 글자로 썼다 | to_md |
MARKUP_WRITTEN_AS_TEXT | Markdown 보기(to_md styled·lossy)의 최종 검사에서 인코더가 쓰지 않는 마크업(raw HTML, 만들지 않은 링크·그림, 링크 참조 정의)이 나온 문단을 모든 구두점을 escape 한 평문으로 다시 썼다. 정상이면 나오지 않는다 | to_md |
CONTENT_LOST | 담지 못한 내용을 뺐다 — 디코드에서는 문서의 내용을 모델이, 인코드에서는 모델의 컨트롤을 HWPX가 담지 못했다. Markdown에서는 styled 보기의 <!-- chart -->·<!-- memo: … --> 주석을 읽지 않고 건너뛰었다 | 디코드하는 연산, from_json, convert_md |
LIST_SEMANTICS_LOST | 목록 문단이 목록 의미(종류·수준·체크) 없이 쓰였다 — Markdown 보기가 표 칸·글상자·각주·캡션 안의 목록 문단을 글로 쓸 때, 또는 Markdown 목록 항목 안의 제목·구분선이 항목 밖 문단이 될 때. 문단마다 하나, message 가 구역과 위치를 가리킨다 | to_md, convert_md |
LIST_START_NORMALIZED | 1 이 아닌 수로 시작하는 Markdown 번호 목록을 1 부터 썼다 | convert_md |
LIST_LEVEL_CLAMPED | 수준 9 보다 깊은 Markdown 목록을 수준 9 로 썼다 | convert_md |
LIST_DEFINITION_MISSING | 템플릿에 그 종류(글머리표·번호·체크)의 목록 정의가 없어 Markdown 목록 항목을 목록이 아닌 문단으로 썼다. 종류마다 하나 | convert_md |
NUMBERING_PRESENTATION_LOST | 번호 정의의 번호를 원래대로 보이지 못한다 — Markdown 에서는 상위 수준 번호를 쓰는 서식(^1.^2)이 있거나, 번호 정의 복제가 1024 번을 넘어 뒤의 목록이 템플릿 번호 정의를 함께 쓸 때(기본 템플릿에서는 1026 번째 독립 목록부터), Markdown 보기에서는 한컴 문서의 같은 번호 정의가 다른 블록 뒤에서 이어질 때(다시 1 부터 씀). 정의마다 하나 | convert_md, to_md |
IMAGE_REFERENCE_UNRESOLVED | 그림·채우기가 가리키는 이미지가 패키지에 없다 — 대개 from_json에 base를 주지 않았을 때 | from_json (재인코드 편집은 거부) |
XML_FORBIDDEN_CHARS_REMOVED | XML이 담을 수 없는 제어 문자(탭·줄바꿈 제외)를 지우고 썼다 — 편집 연산은 넘긴 값마다 하나, message가 필드·문단·셀·슬롯을 가리킨다(본문 글자의 U+001F는 지우지 않고 고정폭 빈칸으로 쓴다). 문서를 다시 쓰는 경로는 필드 이름·필드 매개변수 같은 XML 위치마다 하나, message가 그 요소·속성을 가리킨다 | fill·patch·insert_para·set_cell·stamp, 재인코드 경로 |
BEGIN_NUM_REPAIRED | 문서 머리의 시작 번호(쪽·그림·표·수식)가 0이었다 — 1 이상이어야 하므로 다시 쓸 때 1로 고친다(이전 판의 HwpForge 출력에 남은 흔적, 손실 아님) | 디코드하는 연산 |
| 디코더 경고 | 문서가 가졌지만 모델이 담지 못한 것(예: 알 수 없는 컨트롤) | 디코드하는 모든 연산 |
CONTENT_LOST는 입력을 Core로 읽을 때 표현하지 못한 정보가 있다는 경고입니다. 원문 보존 삭제는 그 정보가 출력 원문에 보존되고 삭제 판정에 영향을 주지 않음을 별도로 확인한 경우에만 성공하며, 입력 decode 경고는 순서와 횟수 그대로 남습니다. 이는 원문 XML에 정보가 남는 일부 손실(예: 언어별 글자 값)에만 해당하며, 그 밖의 CONTENT_LOST 입력은 기존 거부를 유지합니다. 전체 재인코드 편집의 입력 손실 거부는 유지됩니다.
같은 경고를 validate()의 warnings로도 볼 수 있으므로, 문서를 처음 받았을 때 한 번 validate()를 부르는 것이 좋은 시작입니다.
HwpForgeError — 공통 예외, 다섯 속성
입력을 받아들인 뒤 연산이 거부하면 HwpForgeError를 던집니다. str(exc)는 "CODE: message"(힌트가 있으면 둘째 줄에 hint: …)입니다.
| 속성 | 타입 | 내용 |
|---|---|---|
code | str | 안정된 실패 코드. 분기는 이 문자열로 |
message | str | 무엇이 잘못됐는지 한 문장 |
hint | str | None | 어떻게 해야 하는지 — 연산이 알 때만 |
cause | dict | None | 두 번째 분류. 현재는 PDF_RENDER_FAILED만 {"stage", "code", "kind"?, "location"?}를 가짐 |
details | dict | None | 구조화된 페이로드. ENCODE_SEMANTIC_LOSS는 {"warnings": [...], "others": [...]} |
try:
doc.set_cell(table=0, at="9,9", text="값")
except hwpforge.HwpForgeError as exc:
if exc.code == "CELL_NOT_FOUND":
...
elif exc.code in ("INPUT_ENTRIES_NOT_CARRIED", "INPUT_NOT_ROUNDTRIP_SAFE"):
... # 한컴 저장 문서 — patch 경로로
else:
raise
code는 대응하는 연산에서 같은 단계·사유라면 CLI·MCP·Python 모두 canonical OpsCode 문자열을 사용합니다. 검사 순서와 메시지·힌트는 창구마다 다를 수 있습니다.
다른 예외
| 예외 | 언제 |
|---|---|
TypeError / ValueError | 인자 변환 실패 — fill 값에 정수, font_dirs에 문자열 하나, Document(…)에 bytes 아닌 것 |
HwpForgeIOError (OSError도 포착) | Document.open·save의 파일 I/O |
AttributeError | Document 속성 대입·삭제(불변) |
pyo3_runtime.PanicException | 내부 Rust panic — 버그이니 이슈로 알려 주세요 |
코드 표
전자서명·암호화 표지가 있는 문서는 편집할 수 없으며, 이 거부 오류는 decode 단계의 DECODE_FAILED로 보고됩니다.
각 연산이 자기 특성 실패로 내는 코드입니다. 포함된 읽기·편집 연산은 HWP5(.hwp)를 자동 변환하며, 편집의 의미 손실은 HWP5_CONVERSION_LOSS로 거부합니다. from_json(base=...)·patch·restyle만 HWP5_INPUT으로 거부합니다. 변환 손실과 저장 보호를 참고하세요. 자동 변환 단계의 디코드 실패는 HWP5_DECODE_FAILED이며 변환·검증·인코드 실패는 각각 HWP5_CONVERT_FAILED·VALIDATION_FAILED·ENCODE_FAILED입니다. HWPX 입력의 디코드 실패는 fill·patch·set_cell·insert_para·delete_para·stamp·stamp_plan을 포함해 DECODE_FAILED입니다. 편집 전 no-op 검증·인코드·재디코드 실패는 INPUT_NOT_ROUNDTRIP_SAFE입니다. 코드는 hwpforge::foundation::diagnostics::OpsCode의 문자열 그대로이며, 아래 표는 Python이 부르는 연산에서 실제로 나올 수 있는 것만 적었습니다.
| 연산 | 코드 |
|---|---|
Document.open | INPUT_TOO_LARGE |
| 보류 연산에 HWP5를 전달 | HWP5_INPUT — CLI hwpforge convert-hwp5 <in.hwp> -o <out.hwpx> 또는 Python convert_hwp5로 먼저 변환 |
| 그 밖에 HWPX를 디코드하는 연산 | DECODE_FAILED |
read | READ_TARGET_REQUIRED · READ_PARAS_INVALID · READ_PARAS_WITHOUT_SECTION · SECTION_OUT_OF_RANGE · READ_PARA_RANGE_INVALID · TABLE_NOT_FOUND · FIELD_NOT_FOUND · TABLE_GRID_INVALID |
export_section | SECTION_OUT_OF_RANGE · GRID_ADDR_PROJECTION_FAILED · JSON_SERIALIZE_FAILED |
to_json | GRID_ADDR_PROJECTION_FAILED · JSON_SERIALIZE_FAILED |
to_md | INVALID_INPUT (알 수 없는 mode) · ENCODE_FAILED (mode="lossless") · VALIDATION_FAILED |
to_pdf | INVALID_DISCOVERY · UNRECOGNIZED_FORMAT · HWP5_DECODE_FAILED · HWP5_CONVERT_FAILED · VALIDATION_FAILED · ENCODE_FAILED · PDF_RENDER_FAILED (+ cause) |
fill | NO_VALUES · FIELD_NOT_FOUND · FIELD_NAME_AMBIGUOUS · FIELD_NOT_FILLABLE · EMPTY_FIELD_VALUE · FILL_FAILED(필드 목록 진단) · PATCH_FAILED · PROTECTED_FIELD_RANGE · VALIDATION_FAILED · ENCODE_FAILED · INTERNAL_INVARIANT |
set_cell | INVALID_SET_CELL_ARGS · INVALID_SET_CELL_MAP · TABLE_NOT_FOUND · TABLE_GRID_INVALID · CELL_NOT_FOUND · CELL_LABEL_AMBIGUOUS · CELL_HAS_NON_TEXT_CONTENT · CELL_TARGET_DUPLICATE · CELL_TARGET_CONFLICT · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · SELF_VERIFY_FAILED · INTERNAL_INVARIANT · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · ENCODE_SEMANTIC_LOSS |
patch | JSON_PARSE_FAILED · GRID_ADDR_INVALID · SECTION_OUT_OF_RANGE · SECTION_INDEX_MISMATCH · PATCH_FAILED(보존 경로가 받지 않는 변경·metadata) · PROTECTED_FIELD_RANGE · VALIDATION_FAILED · ENCODE_FAILED · INTERNAL_INVARIANT |
insert_para | INSERT_TEXT_REQUIRED · MULTI_PARAGRAPH_TEXT · SECTION_OUT_OF_RANGE · PARAGRAPH_OUT_OF_RANGE · INSERT_BEFORE_SECTION_PROPERTIES · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · PROTECTED_FIELD_RANGE · INTERNAL_INVARIANT · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · SELF_VERIFY_FAILED · SPAN_COUNT_MISMATCH |
delete_para | DELETE_NO_TARGET · SECTION_OUT_OF_RANGE · PARAGRAPH_OUT_OF_RANGE · DUPLICATE_TARGET · REFERENCE_STRANDED · HARD_BREAK_LOSS · EMPTY_SECTION · SECTION_PROPERTIES_PARAGRAPH · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · PROTECTED_FIELD_RANGE · INTERNAL_INVARIANT · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · SELF_VERIFY_FAILED · SPAN_COUNT_MISMATCH |
stamp | INVALID_STAMP_MAP · STAMP_SPEC_STALE · STAMP_MARKER_MISMATCH · STAMP_SPEC_DUPLICATE · STAMP_NAME_EMPTY · STAMP_NAME_DUPLICATE · STAMP_NAME_COLLISION · STAMP_CANDIDATE_UNCOVERED · STAMP_CELL_NOT_ANCHOR · STAMP_CELL_NOT_EMPTY · STAMP_LABEL_DRIFT · STAMP_CELL_NOT_CANDIDATE · CELL_TARGET_DUPLICATE · STAMP_SOURCE_HASH_MISMATCH · STAMP_MANIFEST_INVARIANT · SELF_VERIFY_FAILED · DECODE_FAILED · VALIDATION_FAILED · ENCODE_FAILED · INTERNAL_INVARIANT · TABLE_NOT_FOUND · TABLE_GRID_INVALID · INPUT_ENTRIES_NOT_CARRIED · INPUT_NOT_ROUNDTRIP_SAFE · ENCODE_SEMANTIC_LOSS |
stamp_plan | DECODE_FAILED |
restyle | PRESET_NOT_FOUND · NO_FONTS · VALIDATION_FAILED · ENCODE_FAILED · ENCODE_SEMANTIC_LOSS |
convert_md | PRESET_NOT_FOUND · MD_DECODE_FAILED · STYLE_STORE_FAILED · STYLE_REBIND_FAILED · VALIDATION_FAILED · ENCODE_FAILED |
from_json | JSON_PARSE_FAILED · GRID_ADDR_INVALID · VALIDATION_FAILED · ENCODE_FAILED |
convert_hwp5 | HWP5_DECODE_FAILED(디코더의 스타일·테두리 참조 검사 포함) · VALIDATION_FAILED · ENCODE_FAILED · HWP5_CONVERT_FAILED(줄 배치 정보 재적용) |
schema | INVALID_INPUT (알 수 없는 kind) |
templates·schema를 뺀 대부분의 연산에서 UPSTREAM_UNMAPPED(이 버전이 아직 분류하지 못한 상류 오류)와 INTERNAL_INVARIANT(라이브러리 불변식 위반 — 버그)가 나올 수 있습니다. 둘 다 이슈로 알려 주세요.
fail-closed 거부 읽기 — ENCODE_SEMANTIC_LOSS
재인코드 편집기(stamp·restyle)는 인코딩이 의미를 잃을 것 같으면 바이트를 아예 만들지 않고 거부합니다. 무엇이 문제였는지는 details에 있습니다.
try:
doc.restyle(preset="modern")
except hwpforge.HwpForgeError as exc:
if exc.code == "ENCODE_SEMANTIC_LOSS":
for w in exc.details["warnings"]: # 거부를 일으킨 의미 손상
print(w["code"], w["message"])
for w in exc.details["others"]: # 같은 인코딩이 낸 그 밖의 경고
print("also:", w["code"])
예외를 직렬화·복제할 때
HwpForgeError는 copy·pickle이 다섯 속성을 그대로 보존하도록 __reduce__를 정의합니다. 멀티프로세스 워커에서 예외를 부모로 넘겨도 code·details가 살아 있습니다.
파일 I/O 예외 (0.18)
Document.open의 입력 부재는 HwpForgeFileNotFoundError/FILE_NOT_FOUND, 기타 읽기 실패는 HwpForgeIOError/FILE_READ_FAILED, save의 쓰기 실패는 HwpForgeIOError/FILE_WRITE_FAILED입니다. 크기 상한은 HwpForgeError/INPUT_TOO_LARGE를 유지합니다.
두 I/O 클래스는 HwpForgeError와 OSError로 모두 포착할 수 있고, 입력 부재는 FileNotFoundError로도 포착됩니다. 정확한 타입 비교(type(exc) is OSError)와 PermissionError 등 세부 OS 예외 포착은 보존하지 않습니다. .errno, .strerror, .filename, .filename2, 원래 오류에 있던 .winerror를 보존하며 원래 예외는 __cause__로 연결됩니다. copy·pickle은 클래스·다섯 공통 속성·OS 필드를 보존합니다. native extension과 Python 패키지는 같은 버전을 사용해야 합니다.
Document.save의 부모 디렉터리가 없을 때도 이제 FileNotFoundError 대신 HwpForgeIOError (FILE_WRITE_FAILED)가 발생합니다. save 주변의 except FileNotFoundError는 except HwpForgeIOError 또는 except OSError로 바꾸세요. 입력 부재인 Document.open의 FileNotFoundError 포착은 유지됩니다.
set_cell의 보존 가능한 한 문단·한 Text run 칸에서는 입력 경고를 한 번 유지하고 정리 경고 뒤에 Preview 제거 경고를 한 번 냅니다. 원문 header를 유지한 경우 BEGIN_NUM_REPAIRED는 입력 진단이며 수선 완료를 뜻하지 않습니다. 계획적으로 지운 조판 캐시에 가짜 LAYOUT_CACHE_DROPPED를 추가하지 않습니다. 범위 밖 batch의 기존 인코드·carry 경고 계약은 유지됩니다.