변환과 내보내기
convert_md — Markdown에서 문서 만들기
import hwpforge
source = """---
title: 보고서
---
# 개요
본문입니다.
| 항목 | 값 |
| -- | -- |
| 예산 | 1,000 |
"""
result = hwpforge.convert_md(source, preset="classic")
print(result.report["sections"], result.report["paragraphs"])
print(result.document.inspect()["metadata"]["title"]) # 보고서
result.document.save("report.hwpx")
- Markdown은 GFM이고, 맨 앞의 YAML frontmatter가 문서 메타데이터와 스타일을 정합니다(
title등). 스타일 문법은 Markdown에서 HWPX 로를 보세요. preset은hwpforge.templates()가 나열하는 이름 중 하나입니다(default·modern·classic·latest). 없는 이름은PRESET_NOT_FOUND.- 이미지
는base_dir를 기준으로 읽습니다.base_dir를 주지 않으면 파일 이미지는 버려지고 보고서에 남습니다.base_dir밖의 경로는 읽지 않습니다.
result = hwpforge.convert_md("# 그림\n\n\n") # base_dir 없음
print(result.report["assets"])
# [{'kind': 'dropped', 'occurrence': {'paragraph': 1, 'run': 0}, 'reason': 'no_base_dir'}]
print([w["code"] for w in result.report["warnings"]]) # ['IMAGE_EMBED_SKIPPED']
assets의 각 항목은 kind로 구분됩니다: embedded(key·format 포함), dropped(reason 포함), remote(URL은 내려받지 않습니다).
to_md — 문서를 Markdown으로
doc = hwpforge.Document.open("hancom.hwpx")
styled = doc.to_md() # mode="styled": 스타일 frontmatter 유지
lossy = doc.to_md(mode="lossy") # Markdown 이 못 담는 것은 버리고 warnings 로 알림
print(lossy.text[:200])
print(lossy.report["mode"], list(lossy.report["images"].keys()))
mode="lossless"는 보존 범위의 보존 목록은 보존하고, 거부 목록에 든 개체가 있으면ENCODE_FAILED로 거부하며, 그 밖의 값(문단 스타일, 머리말 등)은 거부 없이 빠질 수 있습니다. 이 출력은 보존 범위를 확인하는 기계용 보기라convert_md가MD_DECODE_FAILED로 거부하므로, 왕복 편집에는to_json/from_json을 사용하세요.- 보고서의
images는 문서가 참조한 이미지의{키: 바이트}입니다. Markdown 텍스트가 그 키를 가리키므로, 파일로 저장할 때 같은 이름으로 옆에 써 두면 됩니다.
to_json · from_json — 전체 문서를 JSON으로
import json
exported = doc.to_json() # styles=True 가 기본
document = json.loads(exported.text) # 키: format_version, document, styles
print(exported.report["document"] == document) # 같은 내용을 dict 로도 줍니다
rebuilt = hwpforge.from_json(exported.text, base=doc)
print(rebuilt.report["paragraphs"], [w["code"] for w in rebuilt.report["warnings"]])
# 3 []
to_json의 JSON은 문서 전체와 style store이며, 표 셀에 격자 주소가 붙어 있습니다.styles=False는 구조만 내보냅니다.from_json은 그 JSON을 다시 인코드해 새 문서를 만듭니다.base를 주면 이미지 바이너리와, 바뀌지 않은 문단의 줄 조판 캐시를 그 문서에서 가져옵니다.base없이 이미지가 있는 문서를 재구성하면 이미지가 빠집니다. 스타일은base에서 오지 않습니다. 값이 있는style_ref가 하나라도 있으면 JSON의styles가 필요해서styles=False로 내보낸 JSON은base를 줘도 거부됩니다. 모든style_ref가null이면 기본 프리셋으로 재구성합니다.- 생성은 fail-closed가 아닙니다: 의미가 손실돼도 거부하지 않고
warnings에 실어 돌려줍니다. 위 예제는 내용을 바꾸지 않아base바이트가 그대로 돌아오므로 경고가 없습니다. 내용을 바꾸면 줄 조판 캐시를 잃은 문단마다LAYOUT_CACHE_DROPPED가 나옵니다(한컴에서 다시 저장하면 복원).base가 없으면 캐시를 싣지 않습니다. - 내용이 바뀌면 한컴 저장 문서의
Preview/*·container.rdf엔트리는base를 줘도 승계되지 않습니다(경고 없음). 텍스트만 바꿀 거라면export_section→patch로 관련 없는 내용을 유지할 수 있습니다. 기존 한컴 미리보기가 있던 문서에서 내용을 실제로 바꾸면 미리보기와 그 연결 정보가 제거되고PREVIEW_REMOVED가 나옵니다. 머리글 정규화 등 문서 재인코드가 필요한 경우는 이 보장 밖입니다. - JSON이 문서가 아니면
JSON_PARSE_FAILED. 스키마는hwpforge.schema(kind="exported-document"). - JSON 에
"format_version": 3가 붙고 문단 여백과 탭 위치는{"unit": "hwpunit" | "char", "value": 정수}입니다. 이전 판이 내보낸 버전 없는 JSON 은 탭 위치가 있으면LEGACY_JSON_TABS로 거부되고, 없으면 여백을 풀어 읽으며LEGACY_PARAGRAPH_MEASURES경고를 냅니다. 원본에서to_json을 다시 실행하십시오. 자세한 규칙은 CLI 레퍼런스의to-json절에 있습니다.
전체 JSON(document/styles)과 구역 JSON(section_index/section/styles/preservation)은 서로 다른 스키마입니다 — 전자는 from_json, 후자는 patch가 읽습니다.
convert_hwp5 — 옛 .hwp를 HWPX로
with open("old.hwp", "rb") as handle:
converted = hwpforge.convert_hwp5(handle.read())
print(len(converted.document), [w["code"] for w in converted.report["warnings"]])
converted.document.save("old.hwpx")
convert_hwp5의 인자는 파일 경로가 아니라 바이트입니다. 지원 읽기·편집 연산은Document.open("old.hwp")으로 연 입력도 자동 변환합니다. HWP5 디코드 실패는HWP5_DECODE_FAILED입니다.- 보고서의
warnings에 HWP5가 가졌지만 HWPX로 옮기지 못한 것이 전부 나옵니다. - 기본값(
carry_layout_cache=True)은 한컴이 계산해 둔 줄 조판 캐시를 함께 옮깁니다. 결과가 원본의 줄 나눔 자리를 담고, PDF 렌더는 이 캐시를 재생합니다(아래). 줄 시작 자리를 정확히 옮길 수 없는 문단은 캐시를 버리고LAYOUT_CACHE_DROPPED로 알립니다. 캐시 없이 쓰려면carry_layout_cache=False를 줍니다.
to_pdf — PDF 렌더
렌더는 문서에 저장된 조판을 재생합니다(다시 계산하지 않습니다). 그래서 조판 캐시가 있는 문서만 렌더 대상입니다: 한컴이 저장한 HWPX, 그리고 convert_hwp5로 캐시를 옮긴 HWPX(기본값). Markdown이나 base 없는 JSON에서 생성한 문서는 캐시가 없어 PDF_RENDER_FAILED입니다.
캐시가 있어도 아직 재생하지 못하는 내용이 있습니다. 한컴이 저장한 문서라도 아래 경우는 실패하고, 한컴에서 다시 저장해도 풀리지 않습니다.
cause["code"] | 언제 | 예 |
|---|---|---|
INVALID_CACHE | 문단 안에 재생하지 못하는 요소(각주·수식·상호참조 등 일부 필드·차트·도형 등)가 있음. 누름틀·하이퍼링크는 저장 방식에 따라 다르고, 메모만으로는 거부되지 않음 | 상호참조·각주·수식이 든 문단 |
UNSUPPORTED_CONTENT | 아직 지원하지 않는 배치 — cause["kind"]가 무엇인지 말함 | kind == "non-default table position" |
이 경우에 걸리는 문서는 한컴에서 PDF로 저장하세요.
with open("old.hwp", "rb") as handle:
carried = hwpforge.convert_hwp5(handle.read()).document
try:
pdf = carried.to_pdf(font_dirs=["/Library/Fonts/Hancom"])
print(pdf.report["pages"])
with open("old.pdf", "wb") as out:
out.write(pdf.data)
except hwpforge.HwpForgeError as exc:
print(exc.code, exc.cause)
# PDF_RENDER_FAILED {'stage': 'render', 'code': 'FONT_UNRESOLVED'} ← 글꼴을 못 찾음
# PDF_RENDER_FAILED {'stage': 'render', 'code': 'NO_RENDERABLE_CACHE', 'location': 's0'} ← 캐시 없음
# PDF_RENDER_FAILED {'stage': 'render', 'code': 'INVALID_CACHE'} ← 재생할 수 없는 요소가 든 문단
- 글꼴은 기본 fail-closed입니다: 문서가 이름 붙인 글꼴 face를
font_dirs안에서 찾지 못하면 추측하지 않고 실패합니다(cause["code"] == "FONT_UNRESOLVED").degraded=True는 대체 글꼴로 렌더하며, 결과의 모양이 달라집니다. discovery는font_dirs밖을 더 볼지의 선택입니다:"explicit"(기본, 결정적) ·"hancom"(한컴 설치 글꼴 위치) ·"platform"(OS 글꼴).font_dirs는 시퀀스여야 합니다. 문자열 하나를 주면 한 글자짜리 디렉터리들로 읽히는 대신TypeError로 거부됩니다.partial_cache_reject=True는 캐시가 일부만 있는 문서를 다시 배치하지 않고 거부합니다.- 실패의 두 번째 분류는
exc.cause에 옵니다(stage·code·kind·location).exc.hint는 캐시가 없는 경우(NO_RENDERABLE_CACHE·MISSING_LAYOUT_CACHE, 한컴 재저장), 지원하지 않는 내용(UNSUPPORTED_CONTENT, 한컴에서 PDF 저장), 캐시가 재생과 맞지 않는 경우(INVALID_CACHE, 재저장 또는 메시지가 가리키는 내용에 따라 한컴 PDF 저장)만 가르고 그 밖에는 같은 문장이므로, 무엇을 할지는cause["code"]로 가르세요:FONT_UNRESOLVED는font_dirs·discovery,NO_RENDERABLE_CACHE·MISSING_LAYOUT_CACHE는 한컴에서 다시 저장,INVALID_CACHE·UNSUPPORTED_CONTENT는 위 표.
templates · schema
for preset in hwpforge.templates()["presets"]:
print(preset["name"], preset["description"], preset["font"], preset["page_size"])
schema = hwpforge.schema(kind="exported-section") # "document" | "exported-document" | "exported-section"
print(schema["title"], list(schema["properties"])[:4])
두 함수의 결과에는 warnings가 없습니다. schema는 JSON Schema dict이며 키는 스키마 자신의 것입니다.
스타일 참조는 style_ref와 styles.style_positions를 함께 보존하세요. styles 없는 독립 import에서 non-null 참조는 오류입니다. 명시 v2 입력은 위치 의미로 v3에 이행합니다.