# python-hwpx 7.0 이주 가이드 7.0 은 python-hwpx 를 "파일에 적힌 대로 읽고 쓰는" 한/글 문서의 기본 엔진으로 정리한 판이다. 6.12.0 에서 7.0.0 으로 올리면 네 가지가 달라진다. 1. **저장** 은 `doc.save(target)` 하나다 — [저장](#저장). 2. **변환·짐작 기능**(Markdown·HTML, ingest, 이름표로 칸 찾기, 메일 머지, 미리보기 …)은 python-hwpx-automation 으로 옮겼다 — [옮겨 간 기능](#옮겨-간-기능). 3. **공개 이름** 을 한 가지 규칙으로 맞추고 얼렸다 — [이름 규칙과 바뀐 이름](#이름-규칙과-바뀐-이름). 4. 몇몇 호출의 **결과** 가 달라진다 — 아래 표들의 "옛 동작을 유지하는 법". 지운 이름·인자를 부르면 대부분 새 자리와 한 줄 예를 알려 주는 오류가 난다. 테스트를 한 번 돌려 오류가 가리키는 대로 고치고, 오류 없이 결과만 달라지는 것은 아래 표로 확인한다. 가장 먼저 바로 아래 `new()` 의 첫 줄을 본다. 표의 왼쪽 열에는 6.12.0 에 있던 이름과 함께, 6.12.0 뒤 7.0 을 만드는 동안에만 있던 이름도 들어 있다(저장소의 main 을 따라 쓴 경우를 위한 것이다). 6.12.0 에서 그 이름이 없었다면 그 줄은 건너뛴다. ## 가장 먼저 볼 것 — `HwpxDocument.new()` 의 첫 줄 | 무엇이 달라지나 | 옛 동작을 유지하는 법 | |---|---| | `new()` 로 만든 문서에 처음 더한 문단(`add_paragraph`, `add_heading`)이 구역 설정을 담은 빈 첫 문단의 자리를 차지한다. 6.x 문서는 늘 빈 줄로 시작했다. **문단 번호가 하나씩 당겨진다**: 6.x 의 `doc.paragraphs[1]` 이 7.0 의 `doc.paragraphs[0]` 이다. 구역 설정과 먼저 넣어 둔 머리말·꼬리말·쪽 번호는 그 문단으로 옮겨 간다 | `HwpxDocument.new(empty_first_line=True)` | 달라지지 않는 경우: 표나 개체를 먼저 더한 문서(빈 줄 다음에 온다), 첫 줄을 직접 쓴 문서 (`doc.paragraphs[0].text = ...`), `open()` 으로 연 문서. 이 변경으로 함께 고쳐야 하는 습관이 둘 있다. - **빈 첫 줄을 지우던 코드는 지운다.** 6.x 에서 흔하던 `doc.paragraphs[0].remove()`· `section.remove_paragraph(0)` 는 7.0 에서 방금 쓴 첫 문단을 지운다(구역 설정은 다음 문단으로 옮겨 가 남는다). `paragraphs[0].runs[0].remove()` 는 구역 설정을 담은 런을 지우는 호출이라 7.0 이 거부한다 (`paragraph-run-section-settings`). - **문단 번호와 `runs[0]` 에 기대지 않는다.** `add_paragraph()` 가 돌려준 문단 객체를 그대로 쓴다. 첫 문단의 첫 런은 구역 설정을 담은 빈 런이라, `paragraph.runs[0]` 이 방금 쓴 글이 아닐 수 있다. ```python from hwpx import HwpxDocument doc = HwpxDocument.new() title = doc.add_paragraph("2026 운영계획") # 7.0: doc.paragraphs[0] (6.x: [1]) title.text = "2026 학교 운영계획" # 번호 대신 돌려받은 객체로 고친다 legacy = HwpxDocument.new(empty_first_line=True) # 6.x 처럼 빈 줄로 시작 legacy.add_paragraph("2026 운영계획") # legacy.paragraphs[1] ``` ## 저장 저장 동사 넷을 `doc.save(target, *, format=None, mode="auto", fallback="error", quality=None, pipeline=None)` 하나로 모았다. `target` 은 경로(str·PathLike)나 이진 스트림이다. 스트림은 쓰기에 더해 `tell()`·`seek()` 가 되고 지금 자리부터 끝까지를 읽거나(`read()`) 지금 자리가 끝이어야 한다 — 실패하면 쓰기 전 모습으로 되돌리고, 저장 뒤 스트림이 쓴 문서를 그대로 담는지 다시 읽어 본다. 스트림에 저장할 문서보다 긴 내용이 있으면 문서 끝에서 자른다(`truncate()`, 못 자르면 거부). `write()` 만 되는 스트림 (파이프·소켓 등)은 `OSError` 로 거부하니 경로에 저장한다. `save()` 는 늘 `MutationReport` 를 돌려준다. 바이트가 필요하면 `doc.to_bytes()` 다(그대로). | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | `doc.save_to_path(path)`, `doc.save_to_path(path, return_report=True)` | `doc.save(path)`. 저장한 경로는 `report.path` | | `doc.save_to_stream(stream)`, `doc.save_to_stream(stream, format="hwp")` | `doc.save(stream)`, `doc.save(stream, format="hwp")`. `format=None` 이면 `.hwp` 경로만 HWP 5.0 으로 쓴다 | | `doc.save_report(target)`(품질 정책 없이) | `doc.save(target, quality=QualityPolicy.transparent()).quality`. `quality=` 를 주지 않은 `save()` 의 `report.quality` 는 `None` 이다(6.x 의 `save_report` 는 정책 없이도 보고를 돌려줬다) | | `doc.save_report(target, quality=q)` | `doc.save(target, quality=q)` 의 `report.quality`. 게이트 실패는 `SaveError`(`quality-gate-failed`)의 `.report`. `before=`·`edit_mask=`·`ledger=` 는 `SavePipeline().run(...)` | | `HwpxDocument.from_package(pkg)` | `HwpxDocument.open(pkg)` | | 저장 뒤 열기 안전 검사를 다시 돌리던 코드 | `report.editor_open_safety` — 저장이 쓴 바이트에 대해 이미 낸 보고 | | 렌더러를 쓰려고 `doc._save_pipeline = SavePipeline(oracle_factory=f)` 를 넣던 코드(비공개 속성) | `doc.save(target, quality=q, pipeline=SavePipeline(oracle_factory=f))`. 7.0 에는 그 속성이 없어 넣어도 쓰이지 않는다. 렌더러는 `q` 가 렌더링할 때만 만들어진다 | 옛 이름을 부르면 `HwpxAttributeError`(`document-name-removed`)가 위 표의 새 호출을 알려 준다. `doc.save(path, mode="fast")` 처럼 없는 `mode`·`fallback` 은 거부하고, `.hwpx`·`.hwp` 가 아닌 이름은 경고한다. ```python import io from hwpx import HwpxDocument doc = HwpxDocument.new() doc.add_paragraph("2026 운영계획") report = doc.save("plan-out.hwpx") # 6.x doc.save_to_path("plan-out.hwpx") print(report.path, [part.path for part in report.changed_parts]) buffer = io.BytesIO() doc.save(buffer) # 6.x doc.save_to_stream(buffer) same = HwpxDocument.open(doc.to_bytes()) # 6.x 의 from_package 도 open 으로 ``` ## 옮겨 간 기능 7.0 의 python-hwpx 는 "파일에 적힌 대로 읽고 쓰는" 엔진만 남긴다. 다른 형식으로의 변환, 양식의 뜻 짐작, 보고서 모양 같은 취향, 미리보기 그리기, 장르 규칙은 **python-hwpx-automation 8.0** 으로 옮겼다. 인자와 결과는 6.x 와 같고, 문서의 메서드였던 것은 문서를 첫 인자로 받는 함수가 됐다. ```bash pip install -U "python-hwpx-automation>=8" # python-hwpx 7.0 을 함께 설치한다 pip install "python-hwpx-automation[xlsx]" # 메일 머지의 .xlsx 명부 pip install "python-hwpx-automation[preview]" # 미리보기의 수식 MathML ``` 옛 이름을 부르면 새 자리와 설치 명령을 알려 주는 오류가 난다. 본체는 자동화 패키지를 import 하지 않는다. `-U` 와 `>=8` 을 빼지 않는다. python-hwpx-automation 7.x 는 python-hwpx 6.x 만 받으므로, 7.x 가 깔린 환경에서 `pip install python-hwpx-automation` 만 치면 그 7.x 를 그대로 두고 python-hwpx 를 6.x 로 되돌린다. 반대로 python-hwpx 만 7.0 으로 올리면 pip 가 충돌을 알리고 자동화 패키지의 일부 모듈이 import 되지 않는다. 둘을 함께 올린다. `hwpx-mcp-server` 를 쓰고 있었다면 그것도 8.0 이상으로 함께 올린다. | 형태 | 오류 | |---|---| | `from hwpx import X`, `from hwpx.tools import X`, `from hwpx.experimental import X`, `from hwpx.equation import X` 등 | `hwpx.MovedToCompanion`(`ImportError`) — 메시지에 `from hwpx_automation... import ...` 한 줄 | | `import hwpx.tools.markdown_import` 등 지운 모듈 | `ModuleNotFoundError` — 메시지에 새 모듈 | | `doc.text.markdown(...)` 등 문서 메서드 | `hwpx.errors.HwpxAttributeError`, `code="document-name-moved"`(`context` 에 `replacement`·`install`). `hasattr` 는 `False` | | python-hwpx 6.x | python-hwpx-automation 8.0 | |---|---| | `hwpx.tools.markdown_import.from_markdown`·`MarkdownStyle` | `hwpx_automation.markdown.from_markdown`·`MarkdownStyle` | | `doc.text.append_markdown(md, ...)` | `hwpx_automation.markdown.append_markdown(doc, md, ...)` | | `doc.text.markdown(...)`, `doc.text.markdown(rich=True, ...)`, `hwpx.tools.markdown_export.export_markdown` | `hwpx_automation.markdown.to_markdown(doc, ...)`, `to_markdown(doc, rich=True, ...)` | | `doc.text.html(...)`, `hwpx.tools.exporter.export_html` | `hwpx_automation.markdown.to_html(doc, ...)` | | `hwpx.tools.exporter.export_markdown` | `hwpx_automation.markdown.to_markdown(doc)` | | `hwpx.tools.markdown_export.equation_markdown` | `hwpx_automation.markdown.equation_markdown` | | `hwpx.HwpxMarkdownConverter`, `hwpx.ingest.*`, `hwpx.experimental` 의 ingest 7개 | `hwpx_automation.ingest.*` | | `hwpx.integrations.langchain.HwpxLoader`, `hwpx.integrations.llama_index.HwpxReader` | `hwpx_automation.integrations.langchain` / `.llama_index` | | `doc.tables.find_cell_by_label(label, ...)`, `form_slots(...)`, `fill_by_path(mappings, ...)` | `hwpx_automation.forms.find_cell_by_label(doc, label, ...)`, `form_slots(doc, ...)`, `fill_by_path(doc, mappings, ...)` | | `doc.fields.choices()`, `doc.fields.choose(selections)` | `hwpx_automation.forms.form_choices(doc)`, `choose(doc, selections)` | | `hwpx.merge_template_rows`·`load_mail_merge_rows`·`inspect_mail_merge_placeholders`·`MAIL_MERGE_REPORT_VERSION`, `hwpx.tools.mail_merge` | `hwpx_automation.mail_merge.*` | | `hwpx.experimental.render_layout_preview`·`LayoutPreview`·`PreviewPage`·`render_document_viewer`·`DocumentViewer`, `hwpx.tools.layout_preview`·`document_viewer` | `hwpx_automation.preview.*` | | `hwpx.equation.render_equation`·`EquationRender`·`LABEL_*`·`latex_to_mathml`·`latex2mathml_available`·`MathMLUnavailableError` | `hwpx_automation.preview.*` | | `hwpx.tools.format_rules`, 명령 `hwpx-check-format` | `hwpx_automation.format_rules`, 같은 이름의 명령(python-hwpx-automation 이 선언) | | `hwpx.tools.table_cleanup`, `hwpx.tools.report_utils` | `hwpx_automation.office.utilities` | | `hwpx.inspect_reference_consistency`, `REFERENCE_CONSISTENCY_REPORT_VERSION` | `hwpx_automation.office.compliance` | | 루트 옛 이름 `doc.export_markdown()`·`export_rich_markdown()`·`export_html()`·`fill_by_path()`·`find_cell_by_label()` | 위 `to_markdown`·`to_html`·`forms.*` | | `hwpx-text-extract --format markdown` | `hwpx_automation.markdown.to_markdown(doc)` (평문 추출 `--format plain` 은 그대로) | ```python from hwpx import HwpxDocument from hwpx_automation.forms import fill_by_path from hwpx_automation.markdown import append_markdown, to_markdown doc = HwpxDocument.open("신청서.hwpx") append_markdown(doc, "## 덧붙임\n\n- 확인 완료") # 6.x doc.text.append_markdown(...) result = fill_by_path(doc, {"성명 > right": "홍길동"}) # 6.x doc.tables.fill_by_path(...) markdown = to_markdown(doc, rich=True) # 6.x doc.text.markdown(rich=True) ``` 엔진에 남는 것: 평문(`doc.text.plain()`)·`outline`·`paragraphs`·`blocks`, 표 지도 (`doc.tables.map()`), 수식 변환(`latex_to_eqedit`·`eqedit_to_latex`)과 측정, 한/글의 메일 머지 **필드**(`paragraph.add_mail_merge_field`), 문서 합치기, 차례, 문서 비교(`doc_diff`), 변경 추적, 칸 맞춤 (`hwpx.form_fit`), 줄 배치 캐시, 품질 게이트. 미리보기가 쓰는 `EQEDIT_MATHML_OPERATOR_COMMANDS` 는 `hwpx.equation` 에서 내보낸다. 달라지는 점: - `to_markdown`·`to_html` 은 **문서** 를 받는다. 6.x `hwpx.tools.exporter.export_markdown`·`export_html` 은 패키지 바이트도 받았다(`hwpx_automation` 은 바이트를 받지 않는다). 바이트는 `HwpxDocument.open(data)` 로 연 뒤 넘긴다. - 본체의 `MarkdownStyle` 객체는 새 `from_markdown` 이 받지 않는다(클래스가 다르다). `hwpx_automation.markdown.MarkdownStyle` 을 쓴다. - extra `xlsx`·`preview`·`langchain`·`llamaindex` 는 `pip install "python-hwpx[xlsx]"` 가 깨지지 않게 이름만 남고 아무것도 설치하지 않는다(5.0 의 `visual` 과 같다). 그 의존성은 python-hwpx-automation 의 같은 이름 extra 가 끈다. - 오류 code `ingest-failed`·`ingest-format-unsupported`·`equation-mathml-unavailable`·`text-markdown-style-invalid`· `table-path-invalid-type` 는 그 기능과 함께 옮겨 갔다(자동화 패키지가 같은 code 로 내고, 예외는 모두 `hwpx.errors.HwpxError` 계열이다). - `except hwpx.ingest.DocumentIngestError` 처럼 옛 모듈의 예외를 잡던 코드는 `hwpx_automation.ingest` 의 같은 이름으로 바꾼다. ## 이름 규칙과 바뀐 이름 7.0 이 마지막 이름 변경이다. 7.0 의 공개 이름(최상위 `hwpx.__all__`, 루트 `HwpxDocument`, 묶음 `doc.styles`·`doc.page` …, `hwpx.model` 의 계약 멤버, `hwpx.objects` 값 형식, 안정 모듈 이름)은 8.0 전에는 지우거나 바꾸지 않는다. 저장소의 `tests/data/public_surface.json` 이 그 목록이다. ### 규칙 새 이름은 다음 규칙을 따른다. 처음 보는 이름도 이 규칙으로 짐작할 수 있다. - **값 하나는 속성으로 읽고 쓴다**: `paragraph.alignment = "CENTER"`, `run.size = 14`, `cell.vertical_alignment = "CENTER"`, `obj.rotation = 90`. 여러 값을 한 번에 바꾸는 것만 `set_…(...)` 메서드다(`set_position`, `set_borders`, `set_format`). - **인자 없는 읽기는 속성, 인자를 받는 읽기는 메서드** 다. `get_` 을 붙이지 않는다(`table.cell_map`, `properties.header()`). 묶음의 읽기가 `section=` 때문에 메서드여도, 모델 객체에서는 같은 값을 속성으로 읽는다 (`doc.page.headers(section=0)` ↔ `section.properties.headers`). - **여러 개를 돌려주는 읽기는 `tuple`** 이다. 문서 전체를 차례로 훑는 것은 Iterator 를 돌려주는 메서드다. - **줄임말과 XML 이름을 쓰지 않는다**: `vertical_alignment`, `horizontal_relative_to`, `full_size`, `item_id`. - **단위는 이름에 붙인다**: 접미사가 없으면 HWPUNIT(int), `_mm` 은 mm, `_pt` 는 pt. 글자 크기 `size`·`font_size` 는 pt. 선 굵기는 어디서나 `…_width_mm`(mm, float)이다. - **인자 이름**: 문단은 `paragraph=`(하나)·`paragraphs=`(여럿)이고 번호와 문단 객체를 모두 받는다. 구역은 `section=`, 몇 번째는 `index=`, 표 좌표는 `row`·`col`, 머리(`header.xml`) 정의를 가리키는 것은 `…_id_ref`. - **`add_<종류>` 는 그 종류를 읽을 때와 같은 객체를 돌려준다**(`add_hyperlink` → `Hyperlink`). 문단을 담는 모든 그릇 (문서·구역·표 칸·각주·머리말·바탕쪽)의 `add_paragraph` 는 `text` 와 `style=`·`para_pr_id_ref=`·`char_pr_id_ref=` 를 같은 이름으로 받고, 정렬 같은 것은 돌려받은 문단의 속성으로 쓴다. - **같은 이름은 어디서나 같은 값** 이다. `alignment` 는 문단·표·그림 어디서나 `Alignment` 값으로 읽고 문자열로 쓴다. 뜻이 다른 것은 이름을 나눈다(문단의 `page_break` 는 쪽 나눔, 표의 `page_split` 은 쪽 경계에서 나누는 방식). - **한 가지 일은 한 곳에서** 한다(변경 추적은 `doc.tracking`, 서식 정의는 `doc.styles`). - **실패는 `hwpx.errors.HwpxError` 계열** 이고 `code`·`suggestion` 을 싣는다. 대신하는 내장 예외(`TypeError` 등)도 함께 상속한다. ### `.element`는 계약 밖이다 모델 객체의 `.element`(감싼 XML 요소)는 7.0에서도 그대로 쓸 수 있다. 다만 공개 계약이 아니다. 요소의 모양은 판 사이에 바뀔 수 있고, `.element`로 고친 것은 엔진의 거부·검사·줄 배치 캐시 지우기를 거치지 않는다. XML을 직접 고쳤다면 그 문단에 `paragraph.clear_layout_cache()`를 부른다. 7.0에서 공개 API가 생긴 일(문단·런 서식, 표 속성, 개체 배치, 번호·글머리표, 누름틀 값 등)은 공개 API로 옮기기를 권한다. 자세한 것은 [stable-api](stable-api.md)의 「`.element` — 약속하지 않는 탈출구」. ### 안내 오류 6.x 에 나간 이름을 7.0 에서 바꾸거나 지웠으면 새 자리를 알려 주는 오류가 난다. 7.0 개발 중에만 있던 이름은 안내 없이 바뀌었다. | 부른 것 | 오류 | |---|---| | 없어진 메서드·속성(`doc.save_to_path`, `table.get_cell_map` …) | `HwpxAttributeError`(`AttributeError`), `code="document-name-removed"`, `context` 에 `replacement`. `hasattr` 는 `False` | | 없어지거나 바뀐 인자(`row_index=`, `section_index=`, `pageBreak="1"` …) | `HwpxTypeError`(`TypeError`), `code="hwpx-argument-removed"` | | 최상위에서 빠진 이름(`from hwpx import latex_to_eqedit` 등) | `ImportError` 계열, 메시지에 새 `import` 한 줄 | | 옮긴 기능 | [옮겨 간 기능](#옮겨-간-기능) | 오류가 나지 않는 것 — 반환 형식만 바뀐 것과, 같은 이름이 메서드에서 속성이 된 것 — 은 아래 [반환 형식](#반환-형식만-바뀐-것) 표에 있다. ### 루트와 가져오기 | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | 6.0 이 묶음으로 옮기고 경고와 함께 남겨 둔 루트 이름 79개(`doc.set_header_text(...)`, `doc.add_footnote(...)` …) | 묶음의 새 자리(`doc.page.set_header(text=...)`, `doc.notes.add_footnote(...)` …). 오류 문구가 7.0 의 자리를 알려 준다. 6.0 의 대응표는 [6.0 이주 가이드](migration-6.0.md) | | `section_index=` | `section=`(번호·구역 객체) | | `style_id_ref=` | `style=`(이름·번호·`Style`). 스타일의 문단·글자 모양까지 적용한다. 스타일 번호만 붙이려면 `paragraph.style_id_ref = 2` | | `doc.add_paragraph(..., pageBreak="1")` 같은 XML 속성 키워드, `run_attributes=`(`add_paragraph`·`add_heading`·`add_table`·`add_picture`) | 돌려받은 객체의 속성: `p = doc.add_paragraph(...)`; `p.page_break = True` | | `doc.add_picture(..., align=, line_width=33)` → `InlineObject` | `doc.add_picture(..., alignment=, line_width_mm=0.12)` → `Picture` | | `from hwpx import <실험 기능>`(26개) | 엔진에 남은 11개는 `from hwpx.experimental import ...`: 편집 계획(`EditPlan`·`PlanReport`·`PlanValidationError`·`apply_edit_plan`·`validate_edit_plan`), 쪽 수 어림(`estimate_pages`·`PageEstimate`·`EstimatedLine`), 자기 서술(`describe_capabilities`·`contract_document`·`contract_json_schema`). 수식 3개는 아래 줄대로 `hwpx.equation`. 나머지 12개(ingest 7개, 미리보기 5개)는 python-hwpx-automation 으로 옮겼다(위 "옮긴 기능" 표: `hwpx_automation.ingest`·`hwpx_automation.preview`) | | `from hwpx import latex_to_eqedit`(·`estimate_equation_size`·`UnsupportedLatexError`), `hwpx.experimental` 의 같은 이름 | `from hwpx.equation import ...`(7.0 에서 안정 계약) | ### 문단·런·서식 | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | `paragraph.add_new_num(...)` | `paragraph.add_number_restart(...)` → `NumberRestart` | | `paragraph.add_tracked_insert(...)`·`add_tracked_delete(...)` | `doc.tracking.insert(paragraph, text)`·`doc.tracking.delete(paragraph, match=...)` | | `paragraph.add_picture(binary_item_id_ref, align=, line_width=33)` | `paragraph.add_picture(item_id, alignment=, line_width_mm=0.12)` | | `paragraph.add_line`·`add_rectangle`·`add_ellipse`·`add_arc`·`add_polygon`·`add_curve`·`add_connector` 의 `line_width='33'` | `line_width_mm=0.12` | | `paragraph.add_equation(script, base_unit=1100, size=(w, h))` | `paragraph.add_equation(script, font_size=11.0, width=w, height=h)` | | `paragraph.add_chart(..., size=(w, h))` | `add_chart(..., width=w, height=h)` | | `RunStyle.is_superscript()`·`is_subscript()`·`is_emboss()`·`is_engrave()` | 속성 `superscript`·`subscript`·`emboss`·`engrave` | | `RunStyle.text_color()` | `RunStyle.color` | | `Font.binary_item_id_ref`, `FontSubstitution.binary_item_id_ref` | `item_id` | | `ParagraphProperty.align` | `ParagraphProperty.alignment` | ### 개체·수식 | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | `obj.get_attribute(name)` | `obj.attributes.get(name)` | | `shape.set_position(horz_rel_to=, vert_rel_to=, horz_align=, vert_align=)` | `horizontal_relative_to=`, `vertical_relative_to=`, `horizontal_alignment=`, `vertical_alignment=`(그림·수식·표도 같은 이름) | | `shape.set_draw_text(vert_align=)` | `vertical_alignment=`(표 칸과 같은 이름) | | `obj.set_caption(full_sz=)`, `caption.full_sz` | `full_size` | | `estimate_equation_size(script, base_unit=1100)` | `estimate_equation_size(script, font_size=11.0)` | ### 표 | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | `table.cell(row_index=, col_index=)`, `set_cell_text`·`set_cell_shading`·`set_cell_borders`·`set_cell_border_fill`·`set_cell_fill_gradient`·`set_cell_fill_image`·`split_merged_cell` 의 같은 인자 | `row=`, `col=`(위치 인자로 부르면 그대로) | | `table.get_cell_map()` | 속성 `table.cell_map`(tuple 의 tuple) | | `table.insert_rows(..., blank=True)`·`insert_columns(..., blank=True)`(`doc.tables.` 도) | `blank=` 를 지운다 — 빈 칸이 기본이다([아래](#표에-넣는-행과-열은-빈-칸이다)) | | `table.insert_rows(..., blank=False)`·`insert_columns(..., blank=False)` | `copy_content=True` | ### 구역·머리말·바탕쪽·각주 | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | 모델 `Document`·`Section` 의 `add_paragraph(run_attributes=, inherit_outline=, =)` | 없어졌다. 돌려받은 문단의 속성으로 쓴다 | | `header.add_paragraph(text, align="CENTER")` | `p = header.add_paragraph(text)`; `p.alignment = "CENTER"`. 머리말·바탕쪽·각주의 `add_paragraph` 가 `style=`·`para_pr_id_ref=`·`char_pr_id_ref=` 를 받는다 | | `header.apply_page_type` | `header.page_type`(읽고 쓰기). 옛 이름은 읽을 때도 쓸 때도 오류로 새 이름을 알려 준다 | | `properties.get_header()`·`get_footer()` | `properties.header()`·`footer()` | | `properties.start_numbering`·`set_start_numbering(...)` | `properties.start_numbers`·`set_start_numbers(...)` → `hwpx.objects.StartNumbers`(`hwpx.oxml.SectionStartNumbering` 은 없어졌다) | | `properties.add_master_page_reference(id_ref=)` | `add_master_page_reference(master_page_id=)`. `MasterPage` 도 받는다 | | `properties.remove_master_page_reference(id_ref)` | `remove_master_page_reference(master_page_id)`. `MasterPage` 도 받는다 | ### 반환 형식만 바뀐 것 오류가 나지 않으므로 결과를 쓰는 곳을 직접 본다. | python-hwpx 6.x | python-hwpx 7.0 | 고칠 것 | |---|---|---| | 여러 개를 돌려주는 읽기가 `list` | `tuple`: `doc.paragraphs`·`doc.sections`, `doc.oxml.sections`·`headers`·`master_pages`·`histories`, `doc.parts.headers`·`master_pages`·`histories`, `section.paragraphs`·`memos`, `paragraph.runs`·`tables`·`shapes`·`footnotes`·`endnotes`, `table.rows`, `row.cells`, `cell.paragraphs`·`tables`, `properties.headers`·`footers`, `memo.paragraphs` 등 | 목록을 고치던 코드(`append`, `sort`)는 `list(...)` 로 | | `paragraph.bookmarks` → 이름의 `list` | `Bookmark` 의 tuple | 이름은 `[b.name for b in paragraph.bookmarks]` | | `paragraph.footnotes`·`endnotes` 가 그 문단에 든 표의 칸 안 각주·미주까지 돌려줌(두 번 세기도 했다) | 그 문단에 바로 달린 것만 | 본문 문단을 돌며 문서의 각주를 모으던 코드는 `doc.notes.footnotes`·`doc.notes.endnotes` 로 | | `paragraph.hyperlinks` → dict 처럼 읽히는 값 | `Hyperlink` 의 tuple | `link["url"]` 대신 `link.url`·`link.to_dict()` | | `paragraph.add_bookmark`·`add_hyperlink`·`add_form_field`·`add_check_box`·`add_highlight`·`add_page_hiding` → `InlineObject` 또는 `None` | `Bookmark`·`Hyperlink`·`FormField`·`CheckBox`·`Highlight`·`PageHiding` | XML 요소는 `.element`(`Bookmark`·`Hyperlink`·`FormField`·`CheckBox`). `Highlight`·`PageHiding` 은 값만 담고 `.element` 가 없다: 요소가 필요하면 `paragraph.element` 아래에서 찾는다 | | 머리말·꼬리말의 `add_paragraph`·`add_run`·`add_page_number_field` → XML 요소 | 문단·런·개체 객체 | 옛 요소는 `.element` | | `note.add_hyperlink(...)` | `Hyperlink` | | | `HeaderPart.border_fill(id)`·`border_fills` → XML 요소 | `BorderFillInfo` | | | `RunStyle.underline_type()`·`underline_color()`·`outline_type()`, `run.content_kinds()` | 같은 이름의 속성 | 괄호를 뗀다(부르면 `TypeError`) | | `note.text` → 문단 글을 붙여서 | 문단 글을 줄 바꿈(`"\n"`)으로 잇는다 | | | `doc.oxml` 의 서식 읽기 16개(`char_property`·`styles` 등)가 공개 계약 | 계약에서 내렸다(메서드는 남는다) | `doc.styles` 의 같은 이름을 쓴다 | | `doc.styles.names()`, `doc.text.highlights()` | 속성 `doc.styles.names`(tuple)·`doc.text.highlights` | 괄호를 뗀다 | | `doc.styles.char_properties` → `dict` 사본 | 읽기 전용 `Mapping`(머리를 그때 모습으로 읽는 보기, id 하나 찾기는 글자 모양 수와 상관없다) | 고치거나(`chars[id] = …`)·`.copy()` 하던 코드, 받아 둔 값이 그대로 남아야 하는 코드는 `dict(doc.styles.char_properties)` | | `doc.styles.border_fill(id)`·`border_fills`, `numbering(id)`·`numberings` → XML 요소 | `BorderFillInfo`·`NumberingInfo` | XML 요소는 `doc.oxml.border_fill(id)` | | `doc.tracking.changes` → id 를 키로 한 `TrackChange` dict, `change(id)` → `TrackChange` | 문서 순서의 `TrackedChange` tuple, `TrackedChange`(`change_id`·`kind`·`author`·`date`·`paragraph`) | `changes[id]` 는 `doc.tracking.change(id)` 로 | | `doc.tables.all`·`doc.tables[a:b]`, `doc.text.find_runs()`, `doc.notes.memos`, `doc.styles.ensure_numbering()`, `doc.parts.clear_document_metadata()`·`clear_preview()` → `list` | `tuple` | 목록을 고치던 코드는 `list(...)` 로 | | `doc.refs.add_bookmark()`·`add_hyperlink()` → `InlineObject` | `Bookmark`·`Hyperlink` | XML 요소는 `.element` | ### 묶음(`doc.*`)과 값 형식 | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | `doc.text.runs()`·`blocks()` | `doc.text.iter_runs()`·`iter_blocks()`(문서 전체를 차례로 훑는 것은 `iter_`). 7.0 개발 중의 `paragraphs()`·`objects()` 도 `iter_paragraphs()`·`iter_objects()` | | `doc.shapes.add_line`·`add_rectangle`·`add_ellipse`·`add_arc`·`add_polygon`·`add_curve`·`add_connector` 의 `line_width='33'` | `line_width_mm=0.12`(0 은 선 없음) | | `doc.styles.ensure_border_fill(border_width='0.12 mm', base_border_fill_id=)` | `ensure_border_fill(border_width_mm=0.12, base_border_fill_id_ref=)`. 한/글 굵기 목록에 있는 값만 받는다(아래 "결과가 달라지는 것") | | `doc.styles.apply_paragraph_format(paragraph_index=, paragraph_indexes=, line_spacing_percent=, border_width='0.12 mm')` | `apply_paragraph_format(paragraph=, paragraphs=, line_spacing=, border_width_mm=0.12)`. `paragraph=`·`paragraphs=` 는 번호와 문단 객체를 모두 받는다 | | `doc.styles.apply_list_format(paragraph_index=, paragraph_indexes=)` | `apply_list_format(paragraph=, paragraphs=)` | | `doc.styles.ensure_paragraph_format(base_para_pr_id=, line_spacing_percent=)` | `ensure_paragraph_format(base_para_pr_id_ref=, line_spacing=)` | | `doc.styles.ensure_run(base_char_pr_id=)` | `ensure_run(base_char_pr_id_ref=)` | | `doc.styles.ensure_font(binary_item_id_ref=, subst_binary_item_id_ref=)` | `ensure_font(item_id=, subst_item_id=)` | | `doc.styles.border_fill_info(id)` | `doc.styles.border_fill(id)`(→ `BorderFillInfo`). 7.0 개발 중의 `numbering_info(id)` 는 `numbering(id)` | | `doc.page.restart_page_number(p, ...)`·`hide_page_elements(p, ...)` | `doc.page.add_number_restart(p, ...)`(→ `NumberRestart`)·`add_page_hiding(p, ...)`(→ `PageHiding`) | | `doc.page.set_page_number(align=)` | `set_page_number(alignment=)` | | `doc.page.set_columns(separator_width='0.12 mm')` | `set_columns(separator_width_mm=0.12)` | | 7.0 개발 중의 `doc.page.remove_master_page(id)`(구역과의 연결 끊기) | `doc.page.remove_master_page_reference(id)`. 바탕쪽 파트를 지우는 것은 `doc.parts.remove_master_page(id)` | | `doc.parts.add_master_page(..., paragraphs=[...])` → id 문자열 | `mp = doc.parts.add_master_page(...)` → `MasterPage`(id 는 `mp.id`), 글은 `mp.add_paragraph("...")`. `doc.page.set_master_page`·`doc.parts.remove_master_page` 는 `MasterPage` 도 받는다 | | `doc.parts.set_compatible_document_target_program(...)`·`set_layout_compatibility_flags(...)`·`set_doc_option_link_info(path=, page_inherit=, footnote_inherit=)`·`set_license_mark(mark_type=, flag=, lang=)` | `doc.parts.set_document_options(target_program=, layout_compatibility=, link_path=, page_inherit=, footnote_inherit=, license_type=, license_flag=, license_lang=)` → 읽기 `doc.parts.document_options` 와 같은 `DocumentOptions`. 준 것만 바꾼다 | | `doc.parts.set_paragraph_auto_spacing(para_pr_id=)` | `para_pr_id_ref=`(위치 인자로 부르면 그대로) | | `doc.shapes.add_dutmal(main_text, sub_text, pos_type=, align=, sz_ratio=)` → `InlineObject` | `doc.shapes.add_ruby(text, ruby_text, position=, alignment=, size_ratio=)` → `Ruby` | | `doc.shapes.add_composed_character(compose_text, circle_type=, char_sz=, compose_type=)` → `InlineObject` | `add_composed_character(text, frame=, inner_size=, arrangement=)` → `ComposedCharacter` | | `doc.shapes.add_drop_cap(style=)` | `kind=`(`style=` 은 어디서나 문단 스타일) | | `doc.shapes.add_equation(script, base_unit=1100, size=(w, h))` | `add_equation(script, font_size=11.0, width=w, height=h)` | | `doc.shapes.add_chart(..., size=(w, h))` | `add_chart(..., width=w, height=h)` | | `doc.media.replace_picture(picture_index=, binary_item_id_ref=)` | `replace_picture(index=, old_item_id=)` | | `doc.media.picture_references()` → `PictureRef` | `doc.media.pictures`(`Picture`: `item_id`·`width`·`height`, 몇 번째는 tuple 순서) | | `doc.notes.add_footnote(text, p)`·`add_endnote(text, p)` | `add_footnote(text, paragraph=p)`·`add_endnote(text, paragraph=p)` | | `doc.notes.add_memo(anchor=p, anchor_char_pr_id_ref=)` | `add_memo(paragraph=p, paragraph_char_pr_id_ref=)` | | `doc.notes.add_memo(memo_shape_id_ref=id)`(`section.add_memo`·`MemoGroup.add_memo` 도), `memo.memo_shape_id_ref` | 메모 모양은 메모마다가 아니라 구역마다다(한/글은 `hp:secPr@memoShapeIDRef` 에 두고 MEMO 누름틀에는 늘 `65535` 를 쓴다). 쓰기 `doc.notes.set_memo_shape(id, section=i)`(`section="all"` 은 모든 구역), 읽기 `doc.sections[i].properties.memo_shape_id_ref`. 6.x 문서가 누름틀에 적은 id 는 그대로 두며 `memo.attributes["MemoShapeIDRef"]`(6.x `hp:memogroup` 메모는 `["memoShapeIDRef"]`)로 읽는다 | | `doc.fields.fill(value, field_index=, fit_policy=)` | `fill(value, index=, fit=)` | | `doc.tracking.add_change(change_type, author_name=)` | `add_change(change_type, author=)` | 값 형식(`hwpx.objects`)과 그 안의 매핑: | python-hwpx 6.x | python-hwpx 7.0 | |---|---| | `check_box.section_index`(구역 번호) | `check_box.section`(구역 객체). 번호는 `doc.sections.index(check_box.section)` | | `from hwpx.objects import PictureRef`, `PictureRef.picture_index`·`section_index`·`binary_item_id_ref`·`width`·`height` | 없어졌다: `doc.media.pictures` 의 `Picture`(`item_id`·`width`·`height`, 몇 번째는 tuple 순서) | | `ensure_border_fill(sides={"top": {"width": "0.4 mm"}})`, `apply_paragraph_format(border={"width": "0.4 mm"})` | `"width_mm": 0.4`(mm 수, 한/글 굵기 목록의 값). 옛 키는 `style-border-side-invalid`·`paragraph-border-invalid` 로 거부하며 문장이 `width_mm` 을 알려 준다 | | `ContainerMember.rect`·`ellipse`·`polygon`·`line`·`text_box` 의 `line_width="33"`, `text_box(vert_align=)` | `line_width_mm=0.12`, `vertical_alignment=`(도형·`set_draw_text` 와 같은 이름) | | `doc.styles.bullet(id).para_head.align`(문자열) | `.para_head.alignment`(`Alignment`) | | `doc.styles.ensure_memo_shape(line_width=1)`(XML `lineWidth` 를 그대로 적음, 모델 `ensure_memo_shape` 도) | `ensure_memo_shape(line_width_mm=0.12)`. `lineWidth` 는 한/글 굵기 목록의 순번이고(0.12 mm → 1, 0.2 mm → 3) 목록의 값만 받는다. `memo_shape(id).line_width_mm` 은 순번이 아닌 값(`"0.6mm"`)을 한/글처럼 0.1 mm 로 읽는다 | | `doc.page.text_direction(section=s)` → `SectionTextDirection(direction, vertical_header_footer)` | `doc.page.text_direction(section=s)` → `"HORIZONTAL"`·`"VERTICAL"`·`"VERTICALALL"`(표 칸의 `cell.text_direction` 과 같은 말), 머리말·꼬리말 세로쓰기는 `doc.page.vertical_header_footer(section=s)`. 쓰기 `set_text_direction(...)` 은 그대로. 반환 모양이 바뀐 것이라 안내 오류는 없다(`.direction` 을 부르면 `AttributeError`) | 7.0 개발 중에 생긴 값 형식의 이름(안내 없이 바꿈): | 7.0 개발 중 | python-hwpx 7.0 | |---|---| | `RadioButton`·`ComboBox`·`EditBox` 의 `section_index` | `section`(구역 객체) | | `ParagraphPlace`·`ObjectPlace`(`doc.text.iter_paragraphs()`·`iter_objects()`)·`TextMatch`(`doc.text.find()`) 의 `section`(번호) | 구역 객체(바탕쪽이면 `None`). `to_dict()` 의 `"section"` 은 그대로 번호 | | `ObjectPosition.horz_rel_to`·`vert_rel_to`·`horz_align`·`vert_align`(`obj.position`) | `horizontal_relative_to`·`vertical_relative_to`·`horizontal_alignment`·`vertical_alignment`(`set_position` 의 인자와 같은 이름. `to_dict()` 열쇠도 `horizontalRelativeTo` …) | | `NumberingLevel.align`(문자열, `doc.styles.numbering(id).levels`) | `alignment`(`Alignment`. `to_dict()` 열쇠도 `alignment`) | 새로 계약에 올린 것(이름은 그대로, 다음 major 까지 고정): stable 이름이 돌려주던 형식 26개를 `hwpx.objects` 에서도 가져올 수 있다 — `Style`·`RunStyle`·`ParagraphProperty`·`Bullet`·`Font`·`MemoShape`·`TabDefinition`·`TrackChange`·`TrackChangeAuthor`· `SectionGrid`·`SectionVisibility`·`LineNumberShape`·`DocumentMetadata`·`TextBlock`·`TextOutline`·`TextChangeReport`· `ValidationReport`·`Hwp5ConversionReport`·`TableMapResult`·`GridPosition`(`table.cell_map` 의 칸)·`Caption`·`PictureShadow`· `PictureGlow`·`PictureReflection`·`ContainerMember`·`GenericElement`(구현 모듈의 같은 클래스다). `paragraph.section`(문단이 든 구역)도 계약이다. 그림·수식·도형·표도 `obj.section`(바탕쪽이면 `None`)으로 구역을 읽는다 — 6.x 에서 `obj.paragraph.section.element` 를 `doc.sections` 와 견주던 코드는 `doc.sections.index(obj.section)`. 번호 수준은 `NumberingLevel.use_instance_width` (`useInstWidth`)까지 값으로 읽으므로 머리 XML(`hh:paraHead`)을 직접 읽을 필요가 없다. ### 가장 자주 고치는 곳 자동화·학교 도구 저장소에서 센 깨지는 호출 수(받는 쪽을 가리지 못한 수는 상한)가 많은 순서다. 대부분 이름만 바꾸면 된다. | 6.x | 7.0 | 옮기는 법 | |---|---|---| | `doc.save_to_path(p)` | `doc.save(p)` | 이름만. 반환값(경로)을 쓰던 곳은 `report.path` | | `doc.styles.paragraph_property(id).align` | `.alignment` | 이름만 | | `apply_paragraph_format(paragraph_index=, line_spacing_percent=, border_width=)` | `paragraph=`, `line_spacing=`, `border_width_mm=` | 키워드 이름. `border_width_mm` 은 mm 수 | | `doc.save_report(t, quality=q)` | `doc.save(t, quality=q).quality` | 게이트 실패는 반환 대신 `SaveError` | | `table.get_cell_map()` | `table.cell_map` | 괄호를 뗀다 | | `doc.add_picture(..., line_width=33, align=)`, `paragraph.add_picture(binary_item_id_ref, ...)` | `line_width_mm=0.12, alignment=`, `item_id` | 값도 mm 로 | | `doc.add_paragraph(..., pageBreak="1")` | `p = doc.add_paragraph(...)`; `p.page_break = True` | 손으로 | | `ensure_border_fill(border_width="0.4 mm", sides={...: {"width": "0.4 mm"}})` | `border_width_mm=0.4`, `{"width_mm": 0.4}` | 값도 mm 수로 | | `ensure_run(base_char_pr_id=)` | `base_char_pr_id_ref=` | 이름만 | | `RunStyle.text_color()` | `RunStyle.color` | 속성 | | `doc.notes.add_memo(anchor=p)` | `paragraph=p` | 이름만 | | `doc.media.picture_references()`, `PictureRef` | `doc.media.pictures`(`Picture`) | 필드: `binary_item_id_ref` → `item_id`, 번호는 순서 | | `from hwpx.experimental import latex_to_eqedit` | `from hwpx.equation import latex_to_eqedit` | 가져오는 자리만 | ```python from hwpx import HwpxDocument from hwpx.equation import latex_to_eqedit # 6.x from hwpx import latex_to_eqedit doc = HwpxDocument.new() title = doc.add_paragraph("2026 운영계획") title.alignment = "CENTER" # 6.x add_paragraph(..., run_attributes=/XML 속성) table = doc.add_table(2, 2) cell = table.cell(row=0, col=1) # 6.x cell(row_index=0, col_index=1) cell.vertical_alignment = "CENTER" grid = table.cell_map # 6.x table.get_cell_map() rows = list(table.rows) # tuple → 고칠 목록이 필요하면 list(...) equation = title.add_equation(latex_to_eqedit(r"\frac{a}{b}"), font_size=11.0) # 6.x base_unit=1100 ``` ## 만들기·고치기 — 결과가 달라지는 것 | 무엇이 달라지나 | 옛 동작을 유지하는 법 | |---|---| | `add_equation` 이 적는 수식 글꼴이 `HYhwpEQ` 에서 `HancomEQN`(한/글 수식 편집기의 글꼴)으로 바뀌었다. 획이 조금 굵어지고 일부 글자 폭이 달라진다 | `doc.shapes.add_equation(script, font="HYhwpEQ")` | | 수식 상자 폭을 한/글 2024(Windows)가 실제로 필요로 한 폭에 맞춰 다시 잡는다. 같은 수식의 `hp:sz` 폭이 6.x 와 다르다(맥 한/글이 저장한 상자보다 평균 10% 넓다) | 없음(6.x 폭은 수식 뒤 글자와 겹쳤다) | | `section.insert_paragraphs(index, paragraphs)`(`doc.oxml.insert_paragraphs` 도)가 넣는 사본에서 구역 설정(`hp:secPr` 와 단·머리말·꼬리말·쪽 번호 컨트롤)을 뺀다. `index=0` 이면 구역 설정이 옛 첫 문단에서 첫 사본으로 옮겨 간다. 6.x 는 사본에 구역 설정을 남기고 맨 앞에 넣을 때 옛 첫 문단에 두어, 한/글이 그 구역을 기본 용지·여백으로 열었다. 구역 설정이 뒤 문단에 있는 문서는 저장이 `section-properties-not-first` 로 거부된다 | 없음. 이미 그런 파일은 `hwpx-repair` 로 고친다 | | `paragraph.column_break` 를 바꾸면 `page_break` 처럼 그 문단의 줄 배치 캐시(`hp:linesegarray`)가 지워진다. 6.x 는 남겼다. 한/글이 열 때 그 문단을 다시 배치한다 | 없음(옛 줄 배치를 남기지 않는다) | | `add_heading` 뒤에 `add_paragraph` 로 더한 본문이 제목의 문단 모양·스타일(개요)을 물려받지 않는다. 6.x 에서는 한/글이 그 본문에 다음 개요 번호("나." …)를 붙였다 | `doc.add_paragraph(text, inherit_style=True)` | | 정렬을 준 머리말·꼬리말·쪽 번호(`set_header`/`set_footer` 의 `align`, `set_page_number`)가 본문 문단의 테두리·간격을 물려받지 않는다 | 없음(6.x 결과는 쪽 번호 밑에 줄이 그어지던 오류다) | | 머리말·꼬리말을 한/글처럼 첫 문단의 본문 컨트롤(`hp:ctrl`) 한 곳에만 쓴다. 6.x 는 `hp:secPr` 아래에 사본과 `headerApply` 를 하나 더 썼다(OWPML 스키마에 없는 모양, 공개 한/글 저장본 68개에는 없다). 6.x 로 만든 문서는 그 머리말을 다시 설정할 때 사본을 걷어 낸다 | 없음 | | `doc.add_table(style=)`·`doc.add_picture(style=)` 가 스타일의 문단·글자 모양도 적용한다. 6.x 는 스타일 이름표만 붙였다 | 스타일의 모양을 원하지 않으면 `style=` 을 주지 않는다 | | `obj.remove()`·`table.remove()` 가 다른 곳에서 쓰지 않게 된 그림 데이터(`BinData`)도 함께 지운다 | `obj.remove(remove_orphaned=False)` | | 표 칸·글상자·각주·머리말 안에 떠 있게 만든 개체는 문단 기준으로 그 안에 머무르게 놓인다(한/글 저장본의 그 자리 개체들이 쓰는 배치). 본문에 만드는 개체는 그대로다 | 없음(6.x 배치는 한/글에서 표 밖에 그려졌다). 다른 배치는 `set_position(...)` 으로 준다 | | 각주·미주를 더하거나 지우면 같은 종류의 번호를 문서 순서대로 다시 매긴다(쪽마다 새로 매기는 구역은 [아래](#쪽마다-새로-매기는-각주)) | 없음 | | 칸에 색을 칠해도(`set_cell_shading`, `set_shading`) 그 칸의 선·대각선과 그림 배경이 남고, 그러데이션은 새 색으로 바뀐다. 그림을 넣으면 면 색이 남는다. 칸마다 제 테두리 정의에서 사본을 만들므로 `header.xml` 의 테두리 정의가 늘 수 있다 | 없음(6.x 는 같은 색의 다른 정의를 가져와 선이 바뀌거나 사라졌다) | | 글자·문단 모양 변경 추적은 쓰지도 거절하지도 않는다(`track-format-change-unconfirmed`). 한/글 2024 가 다시 저장할 때 그 항목을 버리기 때문이다 | 없음(6.x 의 거절은 표시만 걷어 수락처럼 굴었다) | | `doc.styles["바탕글"]` 처럼 이름·영문 이름·번호로 스타일을 찾는다. `"바탕글" in doc.styles` 도 `True` 다 | `KeyError` 에 기대던 코드는 `in` 으로 묻는다 | | 크기가 0 인 수식·차트, 빈 책갈피 이름, 빈 링크 주소를 거부한다. `paragraph.style` 에 스타일이 아닌 값을 주면 `HwpxTypeError` 다 | 없음 | | 공개 메서드에 잘못된 타입을 주면 `code`·`suggestion` 을 실은 `HwpxError` 계열이 난다(내장 `TypeError` 등도 상속). 문단·런의 글을 잘못 주면 옛 글을 지우기 전에 실패한다 | `except TypeError` 는 그대로 잡는다 | | `doc.refs.cross_references` 의 항목이 살아 있는 `CrossReference` 다(값을 바꾸고 지울 수 있다). 같은지는 요소로 견준다 | 없음 | | `paragraph.clear_layout_cache()` 가 늘 그 문단의 파트를 바뀐 것으로 표시한다. 고치지 않은 문단에 불러도 그 구역을 다시 쓴다(바이트가 읽은 것과 다를 수 있다) | 고치지 않았으면 부르지 않는다 | | `doc.text.iter_paragraphs()`·`iter_objects()` 가 표 캡션 안의 문단과 표를 `where="caption"` 으로 내놓는다(6.x 는 본문·표 칸). `where="body"` 는 이제 `doc.paragraphs` 와 같다 | `where=("body", "caption")` | | 다단 문서에서 새 표와 차트의 기본 폭이 본문 전체 폭이 아니라 단 폭이다 | `width=` 를 준다 | | 구역이 여럿인 문서에서 `doc.page.*` 를 `section` 없이 부르면 마지막 구역만 바뀐다는 경고가 한 번 난다 | `section=` 을 준다. 모든 구역은 `section="all"` | | 테두리·단 구분선·각주/미주 구분선·메모 선 굵기(`border_width_mm=`·`sides`/`border` 의 `width_mm`·`table.set_borders(border_width_mm=)`·`separator_width_mm=`·`ensure_memo_shape(line_width_mm=)`)는 한/글 굵기 목록(0.1·0.12·0.15·0.2·0.25·0.3·0.4·0.5·0.6·0.7·1·1.5·2·3·4·5 mm)의 값만 받는다. 목록에 없는 값(0.45 등)은 문서를 바꾸기 전에 `HwpxValueError`(`style-line-width-invalid`, `suggestion` 에 쓸 수 있는 값)로 거부한다. 6.x 와 7.0 개발 중에는 가장 가까운 값으로 바꿔 썼다. 도형·그림 선(`line_width_mm=`)은 그대로 mm × 283 HWPUNIT 이다 | 목록의 값을 직접 고른다(0.45 → 0.4 또는 0.5). 목록은 `hwpx.oxml.utils.LINE_WIDTHS_MM` 에 있다. 6.x 의 HWPUNIT 선 굵기 `n` 은 `hwpx.oxml.shape_position.line_width_mm_for_units(n)` 이 같은 HWPUNIT 으로 돌아가는 mm 다 | | `obj.rotation = 각도` 가 글이 든 도형(글상자)과 묶음 전체도 돌린다(6.x·7.0 개발 중에는 `shape-rotation-unsupported`). 글은 돌지 않고 돈 도형을 감싸는 상자 폭에 가로로 다시 놓인다(한/글과 같다). 돌린 개체의 숫자는 한/글처럼 cos·sin 소수 여섯 자리로 계산하고 옮기는 양을 정수로 써서, 같은 각도라도 상자 크기·행렬 끝자리가 6.x 와 한 단위쯤 다를 수 있다. 늘인 묶음, 묶음 안 묶음, 이미 돈 묶음을 다른 각도로 돌리는 것도 된다. 각도는 0~359 밖도 받아 한/글처럼 바꿔 쓴다(-30 → 330, 6.x 는 `shape-rotation-value`). 새 속성 `flip_horizontal`·`flip_vertical` 로 사각형·글상자·타원·다각형·선·호·곡선·묶음을 뒤집는다(뒤집힌 개체도 돌고, 돈 개체를 뒤집으면 반대 방향으로 돈 것이 된다). 뒤집힌 개체의 `resize`·그림 자르기는 이제 `shape-flip-unsupported` 로 거부한다(6.x 는 뒤집기 행렬을 옛 크기대로 두어 엇나간 모양을 썼다). 뒤집은 그림과 뒤집은 묶음의 `resize` 를 한/글처럼 쓴다. 돈 개체(그림·도형·묶음, 뒤집힌 것 포함)의 `resize(width, height)` 는 돌리기 전 자기 크기를 받는다: 0 으로 되돌려 크기를 바꾸고 다시 돌린 것과 같아 돈 직사각형이 기울지 않는다(7.0 개발 중 한때 돈 묶음의 `resize` 는 돈 상자의 크기를 받아 쪽의 가로·세로로 늘였고 평행사변형으로 기울었다). 그림(늘인 것도)과 묶음(양쪽·돈 것·늘인 것·늘이고 돈 것도)도 뒤집는다. 한/글 개체 속성으로 돈 상자 크기를 바꿔 기운 개체는 읽고 그대로 두지만 다시 크기를 바꾸거나 돌리거나 뒤집지는 않는다. 묶음 구성원 하나는 여전히 거부한다 | 거부에 기대던 코드는 돌리기 전에 `shape.shape_type == "container"` 등을 직접 본다. 각도 범위 검사에 기대던 코드는 직접 검사한다 | | 떠 있는 개체를 돌리면(`rotation`, 돈 개체의 `resize`) `hp:pos` 의 가로·세로 오프셋이 옮겨진다: 한/글처럼 돌리는 가운데가 쪽 위에서 제자리에 있다(왼쪽·위 기준이면 옛 가운데 − 새 가운데, 가운데 정렬이면 상자 가운데와의 거리 차이). 6.x 는 오프셋을 두어 돈 개체가 회전 이동만큼 오른쪽·아래로 그려졌다. 0으로 되돌리면 언제나 처음 오프셋이다(오프셋은 음수가 될 수 있다). 개체가 걸린 문단은 바꾸지 않는다: 한/글에서 직접 돌리면 위로 올라간 개체를 그 높이 문단에 다시 걸지만(한/글의 쪽 배치) 엔진은 하지 않는다. 쪽 영역 안으로 제한된 개체의 위 끝이 걸린 줄보다 위로 가야 하면 한/글은 그 줄 위 끝에 맞춰 그린다(30° 돌린 수평선이 1400 아래에 그려짐). 묶음을 풀면 구성원이 묶음의 `zOrder` 자리를 이어받고 위의 개체들이 그만큼 올라간다(7.0 개발 중에는 구성원을 맨 위로 올렸다) | 옛 오프셋이 필요하면 돌린 뒤 `set_position(horizontal_offset=, vertical_offset=)` 으로 다시 준다 | | 돈 그림·도형·묶음의 `width`·`height` 가 문단에서 차지하는 상자(`hp:sz`)가 아니라 개체 자신의, 돌리기 전 크기다(`resize` 가 받는 크기와 같은 뜻, `obj.resize(obj.width, obj.height)` 는 아무것도 바꾸지 않는다). 돌지 않은 개체는 전과 같다 | 상자 크기는 새 읽기 전용 `obj.box_width`·`obj.box_height` | | `editable` 속성이 없는 누름틀의 `field.editable` 이 OWPML 스키마 기본값 `True` 다(6.x 는 `False`). 번호 수준(`NumberingLevel`)의 `autoIndent`·`textOffset` 이 없으면 `auto_indent`·`text_offset` 이 스키마 기본값 `True`·`50` 이다(6.x 는 `False`·`0`). 한/글은 이 속성들을 늘 적으므로 한/글 저장본은 전과 같다 | 없음. "적히지 않음"을 따로 보려면 `field.element.get("editable")` | | 용지 크기·여백(`doc.page.size()`·`doc.page.margins()`, `section.properties.page_size`·`page_margins`)이 파일에 적힌 대로다. 적히지 않은 값은 스키마 기본값(용지 59528×84188, 머리말·꼬리말 4252, 제본 0)이고, 기본값이 없는 왼·오른·위·아래 여백이 없거나 숫자가 아니면, 또는 `hp:pagePr`·`hp:margin` 자체가 없으면 `None` 이다(6.x 는 0). 그래서 `PageSize.width`·`height`·`drawn_width`·`drawn_height` 와 `PageMargins` 의 값이 `int | None` 이다. 한/글은 이 값을 늘 적으므로(공개 문서 1,637 구역 모두) 한/글 저장본은 전과 같다 | 셈에 쓰기 전에 `None` 을 본다(`if margins.left is None: ...`). 0 으로 셈하던 6.x 동작은 `margins.left or 0` | | 숨은 설명(`hp:hiddenComment`)의 문단이 `doc.text.iter_paragraphs()` 에서 자기 자리 `where="hidden_comment"` 로 나온다. 7.0 개발 중에는 그 숨은 설명을 담은 문단의 자리(`"body"` 등)로 나왔다 | 그 자리까지 보려면 `where={"body", "hidden_comment"}` | | `doc.text.highlights` 가 본문만이 아니라 표 칸·글상자·캡션·머리말·꼬리말·각주·메모·바탕쪽의 형광펜도 돌려준다(`doc.text.iter_paragraphs()` 의 문단) | 본문 것만: `[h for h in doc.text.highlights if h.paragraph in doc.paragraphs]` | | `doc.save(path, format="hwpx")` 처럼 형식을 밝히면 이름이 `.hwpx` 가 아니어도(임시 이름 `out.hwpx.tmp` 등) 경고하지 않는다. 이름이 `.hwp` 면 여전히 경고한다 | 없음 | | 메모를 MEMO 누름틀의 `hp:subList` 에만 쓴다(한/글 2024 저장 모양). `hp:memogroup` 을 새로 쓰지 않으므로 `doc.sections[i].memo_group` 이 `None` 이고, 문단에 건 메모는 `HwpxOxmlFieldMemo` 다(`memo.element` 는 `hp:fieldBegin`, `move_to` 는 거부 — 메모는 누름틀이 있는 곳에 있다). `doc.notes.add_memo(text)` 처럼 문단에 걸지 않은 메모는 걸기 전까지 저장이 `HwpxValueError`(`note-memo-unanchored`)로 거부된다. 6.x 문서의 메모를 고치면 그 메모를 누름틀로 옮기고 `hp:memogroup` 사본을 지운다 | 메모는 `doc.notes.memos` 로 읽는다. 걸지 않은 메모는 `doc.notes.attach(paragraph, memo)` 로 건 뒤 저장하거나 `doc.notes.remove_memo(memo)` | | `doc.parts.add_master_page(...)` 로 만든 바탕쪽을 저장할 때까지 어느 구역에도 잇지 않으면 저장이 `HwpxValueError`(`master-page-unlinked`)로 거부된다. 6.x 는 잇지 않은 파트를 그대로 썼고, 한/글 2024 는 그 파트를 버렸다(다시 저장하면 바탕쪽과 글이 사라진다). 읽어 온 문서에 있던 바탕쪽은 손대지 않는다 | 만든 뒤 잇는다: `doc.page.set_master_page(mp, section=0)`, 또는 `add_master_page(..., section=0)`. 쓰지 않을 것은 `doc.parts.remove_master_page(mp)` | | MEMO 누름틀의 매개변수를 한/글 2024 저장본과 같은 일곱 개로 같은 순서에 쓴다: `Prop`·`Command`(`MEMO/65535/번호/FILETIME/작성자/\;;`)·`ID`·`Number`·`Author`·`MemoShapeIDRef`(늘 `65535`)·`CreateDateTime`. 6.x 는 `ID`·`Number`·`Author`·`MemoShapeIDRef`·`CreateDateTime` 다섯 개였다. `ID` 는 `memo<번호>` 다(`memo_id=` 로 이름을 준 메모만 그 이름). `CreateDateTime` 은 한/글처럼 그 컴퓨터의 시각이다(끝의 `Z` 는 그대로, 6.x 는 UTC). `Command` 의 FILETIME 이 같은 순간의 UTC 다. 6.x 의 다섯 개 꼴도 그대로 읽는다 | 누름틀 매개변수를 직접 읽던 코드는 시각을 그 컴퓨터 시각으로 읽는다. UTC 가 필요하면 `Command` 의 FILETIME 을 쓴다 | | `doc.text.iter_paragraphs()` 가 MEMO 누름틀 안에만 있는 메모(한/글 2024 가 저장하는 모양)의 문단도 `where="memo"` 로 내놓는다. 6.x 는 `hp:memogroup` 의 메모만 내놓아, 한/글로 다시 저장한 문서에서 메모 글이 빠진 것처럼 보였다(`doc.notes.memos` 는 전에도 읽었다) | 본문 쪽만: `where=` 를 준다 | | `obj.move_to(paragraph)`·`copy_to(paragraph)`(표의 것도)로 개체를 문단 끝에 넣을 때, 마지막 런이 빈 `hp:t` 로 끝나면(빈 문단 등) 개체가 그 빈 `hp:t` 앞에 들어간다(``). 한/글 저장본의 꼴이다(`tests/fixtures/hancom_saved`: 개체와 빈 `hp:t` 만 든 런 4,676개 가운데 빈 `hp:t` 가 끝인 것 4,675, 개체가 끝인 것 1). 7.0 개발 중에는 빈 `hp:t` 뒤에 붙였다. 글이 있는 곳과 `offset` 이 글자 사이인 곳은 전과 같다 | 없음(문단 글과 개체 자리의 뜻은 같다) | | 새로 만든 개체(도형·그림·수식·차트·표·묶음·선·연결선)의 `zOrder` 가 모두 0 이 아니라, 한/글처럼 문서의 지금 최댓값 + 1 이다. 겹쳐 만들면 나중 것이 위에 그려진다. 사본(`copy_to`, 표의 `copy_to`·`copy_after`)은 구역이 아니라 문서 전체의 맨 위로 간다. 같은 코드로 만든 파일의 `zOrder` 값이 6.x 와 다르다 | 0 이 필요하면 만든 뒤 `obj.z_order = 0` | | `HwpxDocument.new(seed=, now=)`·`open(..., seed=, now=)` 의 seed·시각이 그 문서에만 쓰인다. 7.0 개발 중에는 닫을 때까지 같은 스레드 전체에 걸려, 그동안 만들거나 고친 다른 문서(seed 없는 문서도)가 그 seed 의 id 와 그 시각의 메모·변경 추적 날짜를 받았고, 함께 연 seed 문서들은 서로의 난수열을 나눠 써 따로 만들 때와 다른 바이트를 썼다. 만든 순서대로 닫거나 닫지 않고 버린 seed 문서의 seed 는 그 뒤 문서들에 남았다. 다른 문서에서 복사해 온 내용(`paragraph.copy_to`, 개체 `copy_to`, `insert_document`)의 새 id 는 이제 받는 문서의 출처에서 나온다(전에는 마지막에 연 seed 문서의 것). 그룹 부재(`ContainerMember`)는 id 없이 만들어지고(`instid` 가 빈 값) `doc.shapes.add_container` 가 받을 때 그 문서의 id 를 받는다: 부재를 만든 뒤 다른 것을 더하고 나서 묶는 seed 문서는 id 차례가 다르고, 한 부재를 두 묶음에 넣으면 묶음마다 다른 id 다. seed 문서를 하나씩 만들어 닫고 부재를 묶는 식 안에서 만드는 코드의 바이트는 그대로다 | 없음. 두 문서가 같은 난수열을 나눠 쓰던 결과가 필요하면 한 문서에서 만든다 | | `doc.styles.ensure_border_fill(sides={...: None})`(기준 정의에서 파생할 때도)가 선 없는 면을 한/글처럼 `type="NONE" width="0.1 mm"` 로 쓴다. 전에는 기준(또는 `border_width_mm`)의 굵기를 그대로 적었다(`0.12 mm` 등). `tests/fixtures/hancom_saved` 1,257개의 NONE 면 9,772개 가운데 9,768개가 `0.1 mm`, 기준 굵기를 물려받은 꼴은 0 | 굵기를 적어야 하면 `sides={"left": {"type": ..., "width_mm": ...}}` 로 선을 준다 | | `table.set_in_margins(...)` 가 `hasMargin` 이 꺼진 칸(표 안여백으로 배치되는 칸)의 `hp:cellMargin` 도 같은 값으로 쓴다. 전에는 만들 때 값(510/510/141/141)이 남았다. 한/글 저장본은 그런 칸 18,628개 가운데 18,345개가 표 `inMargin` 과 같다. `add_table(in_margins=CellMargins(...))` 로 만들 때 줄 수도 있다 | 칸의 `cellMargin` 을 따로 두려면 그 칸의 `hasMargin` 을 켠다 | | 문단·개체를 복사하면(`insert_after()`, `copy_to`, `insert_paragraphs`, `insert_document`, 개체의 `copy_to`) 선·사각형·타원·호·다각형·곡선·연결선·차트의 `id` 도 새로 매긴다(전에는 그대로라 같은 문서에 같은 `id` 가 둘 생겼다). 사본의 `instid` 는 원본처럼 `id` 와 같다. 새로 만들거나 복사해 넣은 개체의 `id` 는 문서의 다른 개체와 겹치지 않는다(같은 `seed` 로 만든 두 문서 사이에 옮길 때 겹쳤다). 한/글 저장본은 묶음 밖 개체의 `id` 가 늘 서로 다르다(개체가 있는 1,017개 모두). `id` 값이 6.x·7.0 개발 중과 다르다 | 없음(`id` 는 문서 안에서 개체를 가리킬 뿐이다) | | 다른 문서의 문단을 옮길 때(`paragraph.copy_to`, `insert_document`·`append_document`) 받는 문서에 같은 내용의 글꼴·테두리/배경·탭·글자 모양·문단 모양·스타일 정의가 이미 있으면 그것을 쓴다. 전에는 늘 끝에 새로 만들었다(같은 정의가 둘). 새로 만드는 정의는 받는 문서의 마지막 id 다음부터 빈틈없이 매긴다 | 없음(가리키는 정의의 내용은 같다) | | `run.text` 가 런 바로 아래에 적힌 탭(`hp:tab`·탭 `hp:ctrl`, 한/글이 아닌 도구가 쓰는 꼴)도 한 글자로 센다. 그래서 한 문단의 `run.text` 를 이으면 늘 `paragraph.text` 다. 전에는 `hp:t` 안 글만 셌다. `run.text = …` 는 그 탭도 지우고 값의 탭을 `hp:t` 안에 쓴다. 한/글 저장본은 탭을 늘 `hp:t` 안에 쓰므로 그대로다 | `hp:t` 안 글만: `"".join(p.text for p in run.content if p.container == "t")` | | **`table.insert_rows()`·`insert_columns()`(`doc.tables.` 도)가 한/글처럼 빈 행·열을 넣는다.** 6.x 는 기준 칸의 글·개체까지 복사했다. `blank=` 없이 부르던 코드는 오류 없이 결과가 바뀐다([아래](#표에-넣는-행과-열은-빈-칸이다)) | `copy_content=True` | ### 표에 넣는 행과 열은 빈 칸이다 6.x 의 `insert_rows` 는 기준 행을 통째로 복제했다. 제목 행 아래에 줄을 넣으면 제목 글이 새 줄에 그대로 생겼다. 7.0 은 한/글의 "줄 추가하기"와 같다: 새 칸은 기준 칸의 서식(칸 속성·테두리/배경·여백·크기·문단 모양·글자 모양)만 받고 빈 문단 하나를 둔다. 합친 칸이 새 줄을 가로지르면 늘어나는 규칙은 전과 같다. 이 변경은 이름이 그대로라 **오류가 나지 않는다** — `blank=` 없이 `insert_rows`·`insert_columns` 를 부르는 곳을 찾아 확인한다(`blank=` 를 주던 곳은 안내 오류가 난다). ```python from hwpx import HwpxDocument doc = HwpxDocument.new() table = doc.add_table(rows=2, cols=2) table.cell(0, 0).text = "제목" table.insert_rows(0) # 7.0: 새 줄은 빈 칸 (6.x: "제목"이 복사됐다) assert table.cell(1, 0).text == "" table.insert_rows(0, copy_content=True) # 6.x 의 insert_rows(0) 과 같다 (6.x: blank=False) assert table.cell(1, 0).text == "제목" ``` 바이트 편집 `apply_table_ops` 의 `insert_row_by_clone`·`insert_column_by_clone` 은 이름대로 전처럼 복사가 기본이다 (빈 칸은 `"blank": True`). ## 쪽마다 새로 매기는 각주 각주 번호 방식이 "쪽마다 새로"(`ON_PAGE`)인 구역이 하나라도 있으면, 엔진은 각주를 더하거나 지워도 이미 적힌 번호를 다시 쓰지 않고(다른 구역도), 새 각주에는 문서 전체에서의 순번을 적는다. 그 번호는 쪽 배치에 달려 있는데 엔진은 쪽을 배치하지 않기 때문이다. `note.number` 는 그 구역에서 파일에 적힌 값이다. 한/글 2024 는 문서를 열 때 쪽마다 번호를 다시 매겨 그리고, 저장할 때 쪽별 번호를 파일에 적는다(문서 순번 1..6 을 1,2,1,2,1,2 로 고쳐 적었다). 그래서 화면의 번호는 맞지만, 한/글로 다시 저장하기 전의 `note.number` 는 화면의 번호와 다를 수 있다. 쪽마다의 번호가 필요하면 한/글로 한 번 열어 저장한 파일을 읽는다. ## 수식 변환 `latex_to_eqedit`·`eqedit_to_latex` 의 결과가 달라지는 경우. 6.x 결과는 한/글에서 다른 기호로 그려지거나 깨졌다. | 무엇이 달라지나 | 옛 동작을 유지하는 법 | |---|---| | `\mathrm{H_2O}` 처럼 첨자가 든 곧은 글자 묶음을 곧은 글자의 수식(`{rm H _{2} O it}`)으로 바꾼다(6.x 는 `H _ 2 O` 글자 그대로). `\mathrm{km/h}` 는 원문 띄어쓰기를 따른다 | 없음 | | `\text{...}` 안의 `^`·`_` 를 거부한다(`UnsupportedLatexError`) | 첨자는 `\text{}` 밖으로 꺼내거나 `\mathrm{}` 을 쓴다 | | `\frac{1}`, `\sqrt{}`, `x^^2` 처럼 틀린 LaTeX 를 거부한다(`UnsupportedLatexError`). 6.x 는 받아서 한/글에서 깨진 수식을 만들었다 | 없음 | | net, initial, In 처럼 한/글 예약어로 시작하는 이름을 글자로 지킨다(`net` → `"net"`). 6.x 결과는 한/글이 F≠t 같은 다른 기호로 그렸다 | 없음 | | `\text{ 또는 }` 의 앞뒤 공백을 지키고, 따옴표 글의 `%`·`_`·`}` 를 이스케이프한다 | 없음 | | `eqedit_to_latex`: `root3` → `\sqrt{3}`, `a over b^2` → `\frac{a}{b^2}`, `rarrow`·`ANGLE`·`CDOT`·`INF`·`pile`, 붙여 쓴 `sinx` 같은 한/글 낱말을 LaTeX 로 바꾼다 | 없음 | | 받는 표기가 늘었다(유니코드 기호, `\displaystyle`, `\Leftrightarrow`, `aligned` …). `\mathbb`·`\widehat`·`\square` 는 계속 거부하되 대신 쓸 표기를 알려 준다 | 없음 | ## Markdown 가져오기 — `from_markdown`·`append_markdown` (이제 python-hwpx-automation) 아래 동작 변화는 [옮겨 간](#옮겨-간-기능) `hwpx_automation.markdown` 의 함수에 그대로 있다. | 무엇이 달라지나 | 옛 동작을 유지하는 법 | |---|---| | `from_markdown(text)` 이 모양을 주지 않으면 보고서 모양(색 띠 제목 상자, `Ⅰ` 번호 상자, 줄 표, 쪽 번호, 휴먼명조·HY헤드라인M)으로 만든다. 6.12.0 은 꾸미지 않은 모양이었다. `append_markdown(doc, ...)`(6.x `doc.text.append_markdown`) 의 기본은 그대로다 | `from_markdown(text, style="plain")` (또는 `style=MarkdownStyle()`) | | 표의 열 너비를 내용에 맞추고, 머리 행을 가운데로 놓고, 구분선의 `:---`·`:---:`·`---:` 를 열 정렬로 읽는다 | `MarkdownStyle(table_fit_columns=False, table_header_align=None)` | | 목록 안의 목록을 깊이마다 오른쪽으로 들여 쓴다 | `MarkdownStyle(list_indent_mm=0)` | | 중첩 번호 목록을 한/글처럼 `1.` `가.` `1)` `가)` 차례로 매긴다(6.x 는 `1.1.`). `#####`·`######` 제목도 제 수준의 번호를 받는다 | 없음 | ```python from hwpx_automation.markdown import MarkdownStyle, from_markdown # 6.x hwpx.tools.markdown_import doc = from_markdown("# 제목\n\n- 항목\n - 하위 항목\n", style="plain") # 6.12 모양 old_tables = MarkdownStyle(table_fit_columns=False, table_header_align=None, list_indent_mm=0) ``` ## 읽기 — Markdown 내보내기와 ingest (이제 python-hwpx-automation) 아래 동작 변화는 [옮겨 간](#옮겨-간-기능) `hwpx_automation.markdown`·`hwpx_automation.ingest` 에 그대로 있다. | 무엇이 달라지나 | 옛 동작을 유지하는 법 | |---|---| | `to_markdown(doc)`(6.x `doc.text.markdown()`)이 문서 글을 이스케이프한다. 글에 든 ``, `[x](javascript:…)`, `*별표*`, 줄머리 `#`·`-`·`1.` 이 서식이나 HTML 로 읽히지 않는다. 글에 적힌 `$…$` 수식은 그대로 둔다 | 없음 | | 제목을 문단의 개요 수준(개요 번호, `개요 N` 스타일)으로 정한다. `add_heading` 으로 만든 제목이 `#` 으로 나오고, 시험 문항이나 차례 줄이 제목으로 나오지 않는다. 기본 `to_markdown`·`to_html` 도 개요 문단을 제목으로 쓴다 | `to_markdown(doc, headings=False)`, rich 는 `heading_source="text"`(글 모양으로 짐작) | | `notes=True` 의 각주가 각주 문법(`[^fn1]`, HTML 은 ``)으로 나간다(6.x 의 "문장1)1)각주" 꼴이 사라진다) | `notes="inline"` | | `to_html` 이 칸 안 표를 칸 안 표로 둔다 | `to_html(doc, nested_tables=False)` | | ingest(6.x `hwpx.ingest`, LangChain·LlamaIndex 어댑터 포함)의 Markdown 에 머리말·꼬리말·메모·수식(`$LaTeX$`)과 목록 번호가 실리고, 글자색 `` 은 빠진다. 6.x 는 머리말 등을 빼고 `metadata["left_out"]`·`warnings` 에 보고만 했다 | `convert(path, markdown_options={"headers_and_footers": False, "memos": False, "equations": False})` | | 그림을 꺼내지 않을 때(`image_dir` 없이) 그림 캡션이 `*캡션*` 으로 나간다. 6.x 는 캡션까지 뺐다 | 없음 | `to_markdown(doc, rich=True)`(6.x `doc.text.markdown(rich=True)`) 의 새 옵션 `headers_and_footers=`·`memos=`· `equations=`·`list_labels=` 은 기본이 꺼짐이다. ## 양식 채우기와 바꾸기 | 무엇이 달라지나 | 옛 동작을 유지하는 법 | |---|---| | 표 이름표를 공백을 무시하고 견준다(`fill_by_path`·`find_cell_by_label`, 이제 `hwpx_automation.forms`). `"성명"` 으로 `"성 명"` 칸을 찾는다. 대신 공백만 다른 이름표 둘이 한 문서에 있으면 이제 `"ambiguous label"` 이다 | 몇 번째 이름표인지 적는다: `"성명[2] > right"`(실패 결과의 `candidates` 가 고르는 표기를 알려 준다) | | `fill_by_path` 가 호출을 시작할 때의 문서로 모든 경로의 이름표를 먼저 정한다. 한 경로가 써 넣은 값이 다른 경로의 이름표로 잡히지 않고, 결과가 경로 순서에 달라지지 않는다 | 없음(앞 값이 뒤 이름표가 되던 동작에 기대던 코드는 호출을 나눈다) | | `doc.text.replace` 가 기본 범위(본문 문단의 런 하나 안)에서 0건인데 찾는 글이 표 칸·글상자·머리말이나 서식이 다른 런에 걸쳐 있으면 `ReplaceScopeWarning`(`hwpx.errors`)을 낸다. 돌려주는 횟수와 문서는 같다 | 경고만 끄려면 `warnings.filterwarnings("ignore", category=ReplaceScopeWarning)`. 문서 전체를 바꾸려면 `everywhere=True` | ## `.hwp` 와 열기 | 무엇이 달라지나 | 옛 동작을 유지하는 법 | |---|---| | `.hwp` 로 쓰기가 실험 기능이 되었다. `.hwp` 에서 연 문서를 그 원본 경로에 `.hwp` 로 저장하면 `Hwp5Error`(`hwp5-overwrite-source`), 열 때 옮기지 못한 내용이 있는 문서를 `.hwp` 로 쓰면 `Hwp5Error`(`hwp5-write-lossy-source`) 로 거부한다 | `.hwpx` 로 저장한다(두 경우 모두 `.hwpx` 로는 저장된다). 다른 경로의 `.hwp` 로 쓰는 것은 그대로 된다 | | `.hwp` 를 열 때 글자·문단 모양 변경 추적을 옮긴다: 머리에 변경 추적 정의(`hh:trackChanges`·작성자)가 생기고, run 에 `charTcId`, 문단에 `paraTcId` 가 붙는다. `conversion_report` 에 `unconverted["track-changes"]`·`unconverted["range-tag-18"]`·`dropped["range-tag-19"]` 가 더 나오지 않고, 그런 문서도 `.hwp` 로 다시 쓸 수 있다 | 없음(6.x 결과는 한/글이 지운 글까지 보통 글로 그렸다) | | 문서 이력(DocHistory)이 든 `.hwp` 는 경고와 함께 `conversion_report.unconverted["doc-history"]` 로 알린다. 옮기지 못한 내용이 있는 문서라 `.hwp` 로 다시 쓰면 `hwp5-write-lossy-source` 로 거부한다 | `.hwpx` 로 저장한다 | | 개체 바로 앞에서 시작하는 변경 표시가 `hp:t` 안에 들어가고(6.x 는 한/글이 읽지 않는 `hp:run` 바로 아래), 표시 `Id` 를 한/글처럼 모든 변경 범위로 센다 | 없음 | | 테두리/배경 "없음"(id 0)을 가리키던 쪽 테두리·글자 모양·문단 모양·표 칸이, 머리에 새로 더한 "아무것도 그리지 않는" `hh:borderFill` 을 가리킨다. 머리의 테두리 정의가 하나 늘 수 있다 | 없음(OWPML 에는 id 0 이 없다) | | 대각선 칸의 `centerLine`·꺾임(`Crooked`), 채우기 그림의 `bright`·`contrast`, 확인용이 아닌 글머리표의 `checkedChar`, 개체 설명의 줄 바꿈(CR → LF), 앞뒤 공백이 있는 수식의 `xml:space="preserve"` 가 한/글 변환과 같아진다 | 없음 | | 한 구역 스트림에 구역 정의가 여럿인 `.hwp`(한/글이 쓰지 않은 파일)를 그 수만큼 구역으로 연다 | 없음 | | `META-INF/container.xml` 이 가리키는 미리보기(`Preview/PrvText.txt` 등)가 없는 문서를 열고 저장한다. 6.x 는 `HwpxStructureError` 로 거부했다 | 없음 | | HWP 3.x 이하 `.hwp` 를 열면 "File is not a zip file" 대신 지원하지 않는 형식이라고 알린다. 오류 형(`HwpxArchiveError`)은 같다 | 오류 문구를 비교하던 코드는 형이나 `code` 로 비교한다 | ## 되돌리기 `pip install "python-hwpx<7"`. 6.x 라인은 그대로 있다.