# API Reference
## `hwpx.templates`
###
- `blank_document_bytes() -> bytes`
- HWPX . `hwpx.data` `Skeleton.hwpx` , `examples` . `FileNotFoundError` .
***
## `hwpx.package`
###
- `_ensure_bytes(value: bytes | str | ET.Element) -> bytes`
- (part) UTF-8 .
### `HwpxPackage`
####
- `open(source) -> HwpxPackage`
- , `PathLike`, , OPC zip .
####
- `part_names() -> Iterable[str]`
- .
- `has_part(part_name: str) -> bool`
- .
- `get_part(part_name: str) -> bytes`
- (raw bytes) . `KeyError` .
- `set_part(part_name: str, payload) -> None`
- . .
- `get_xml(part_name: str) -> ET.Element`
- `ElementTree` .
- `set_xml(part_name: str, element: ET.Element) -> None`
- .
- `get_text(part_name: str, encoding: str = "utf-8") -> str`
- .
####
- `manifest_tree() -> ET.Element`
- `content.hpf` (lazily parse) .
- `_resolve_spine_paths() -> list[str]`
- (spine) . .
- `section_paths() -> list[str]`
- XML . `section*.xml` .
- `header_paths() -> list[str]`
- XML . `Contents/header.xml` .
#### (Persistence)
- `save(path_or_stream=None, updates=None)`
- editor-open safety // . `bytes` , ZIP .
- `verify_open_safety=False` public API .
- `_write_archive()`, `_write_zip_entry()`, `_write_mimetype()` raw ZIP writer save . `save()` package validation, document validation, reopen .
***
## `hwpx.document`
### `HwpxDocument`
####
- `open(source)`
- HWPX , `HwpxOxmlDocument` XML (wrapper) .
- `new()`
- .
- `from_package(package)`
- `HwpxPackage` .
#### XML
- `package`
- `HwpxPackage` .
- `oxml`
- `HwpxOxmlDocument` .
- `sections`, `headers`
- / .
####
- `memo_shapes`
- .
- `memo_shape(memo_shape_id_ref)`
- . ID .
- `memos`
- .
- `add_memo(...) -> HwpxOxmlMemo`
- . `section` `section_index` , .
- `remove_memo(memo)`
- .
- `attach_memo_field(paragraph, memo, ...) -> str`
- / `paragraph` MEMO (run) . ID , , .
- `add_memo_with_anchor(...) -> tuple[HwpxOxmlMemo, HwpxOxmlParagraph, str]`
- , MEMO , , (, , ID) .
####
- `paragraphs`
- .
- `char_properties`
- (resolved) .
- `char_property(char_pr_id_ref)`
- ID `RunStyle` .
- `ensure_run_style(...) -> str`
- // ID . .
- `iter_runs()`
- `HwpxOxmlRun` (yield).
- `find_runs_by_style(...) -> list[HwpxOxmlRun]`
- , .
- `replace_text_in_runs(search, replacement, ...) -> int`
- `find_runs_by_style()` . , .
####
- `add_paragraph(text="", ...) -> HwpxOxmlParagraph`
- . .
- `remove_paragraph(paragraph_or_index, section=None, section_index=None)`
- . . `section`/`section_index` .
- `add_section(after=None) -> HwpxOxmlSection`
- . `after` . manifest/spine .
- `remove_section(section_or_index)`
- . . `ValueError` .
- `add_table(rows, cols, ...) -> HwpxOxmlTable`
- , . `inherit_style=True` . `border_fill_id_ref` `borderFill` .
- `get_table_map() -> dict`
- `table_index`, `paragraph_index`, , , , .
- `find_cell_by_label(label_text, direction="right") -> dict`
- , `right`/`down` . .
- `fill_by_path(mappings) -> dict`
- `" > > "` . , , .
- `add_line(start_x, start_y, end_x, end_y, *, line_color, line_width, ...) -> HwpxOxmlShape`
- . HWPUNIT(1 = 7200).
- `add_rectangle(width, height, *, ratio, line_color, line_width, fill_color, ...) -> HwpxOxmlShape`
- . `ratio` (0 = , 50 = ).
- `add_ellipse(width, height, *, line_color, line_width, fill_color, ...) -> HwpxOxmlShape`
- .
- (`offset``orgSz``curSz``sz``pos`
) . .
- `add_shape(shape_type, ...) -> HwpxOxmlInlineObject`
- ** .** ,
.
`UserWarning` .
`validate_package``validate_editor_open_safety`
. .
- `add_control(...) -> HwpxOxmlInlineObject`
- ** .** (: ) .
`add_shape` .
#### (Persistence)
- `save_to_path(path) -> str | PathLike[str]`
- XML .
- `save_to_stream(stream) -> BinaryIO`
- XML .
- `to_bytes() -> bytes`
- XML HWPX ZIP .
- `save(path_or_stream=None) -> str | PathLike[str] | BinaryIO | bytes`
- . `save_to_path()`/`save_to_stream()`/`to_bytes()` `DeprecationWarning` .
***
## `hwpx.tools.package_validator`
- `validate_editor_open_safety(source) -> EditorOpenSafetyReport`
- `from hwpx import validate_editor_open_safety` `from hwpx.tools.package_validator import validate_editor_open_safety` . package validation, document validation, handoff .
- `validate_package(source) -> PackageValidationReport`
- `from hwpx import validate_package` `from hwpx.tools.package_validator import validate_package` . ZIP/OPC/HWPX editor-open hard error .
***
## `hwpx.tools.archive_cli`
- `pack_hwpx(input_dir, output_path, *, overwrite=False) -> PackResult`
- pack-ready HWPX , ZIP . `PackResult.open_safety` `validate_editor_open_safety(...).to_dict()` .
- `unpack_hwpx(source, output_dir, *, overwrite=False, pretty_xml=False) -> UnpackResult`
- HWPX . HWPX , `pack_hwpx()` .
***
## `hwpx.tools.repair`
- `repair_repack(source, output_path, *, overwrite=False, ...) -> RepairResult`
- ZIP HWPX /, CRC, package validation, editor-open safety . `RepairResult.open_safety` handoff evidence.
- `repair_from_recovered(source, output_path, *, overwrite=False, ...) -> RepairResult`
- Local File Header HWPX , .
***
## `hwpx.oxml.common`
### `GenericElement`
- .
###
- `parse_generic_element(node) -> GenericElement`
- XML `GenericElement` .
***
## `hwpx.oxml.body`
###
- `TextSpan`
- , .
- `Run`
- , , `` .
- `Paragraph`
- `` .
- `Section`
- `` .
###
- `parse_text_span(node) -> TextSpan`
- `` `TextSpan` , .
- `parse_run_element(node) -> Run`
- `` `Run` , .
- `parse_paragraph_element(node) -> Paragraph`
- `` `Paragraph` .
- `parse_section_element(node) -> Section`
- `` `Section` .
***
## `hwpx.oxml.header`
###
- `BeginNum`: .
- `LinkInfo`: .
- `LicenseMark`: .
- `DocOption`: `LinkInfo` `LicenseMark` .
- `KeyDerivation`: .
- `KeyEncryption`: base64 .
- `TrackChangeConfig`: .
- `FontSubstitution`: .
- `FontTypeInfo`: .
- `Font`: / .
- `FontFace` / `FontFaceList`: .
- `BorderFillList`: .
- `TabProperties`: .
- `NumberingList`: .
- `CharProperty`: .
- `CharPropertyList`: `CharProperty` .
- `ForbiddenWordList`: .
- `MemoShape`: , `matches_id()` .
- `MemoProperties`: ID `shape_by_id()` ID `MemoShape` `as_dict()` .
- `RefList`: , , .
- `Header`: `memo_shape()` .
###
XML , (: `parse_int` `parse_bool` ). .
- `parse_begin_num(node) -> BeginNum`
- `parse_link_info(node) -> LinkInfo`
- `parse_license_mark(node) -> LicenseMark`
- `parse_doc_option(node) -> DocOption`
- `_decode_base64(value) -> Optional[bytes]`
- `parse_key_encryption(node) -> Optional[KeyEncryption]`
- `parse_track_change_config(node) -> TrackChangeConfig`
- `parse_font_substitution(node) -> FontSubstitution`
- `parse_font_type_info(node) -> FontTypeInfo`
- `parse_font(node) -> Font`
- `parse_font_face(node) -> FontFace`
- `parse_font_faces(node) -> FontFaceList`
- `parse_border_fills(node) -> BorderFillList`
- `parse_char_property(node) -> CharProperty`
- `parse_char_properties(node) -> CharPropertyList`
- `parse_tab_properties(node) -> TabProperties`
- `parse_numberings(node) -> NumberingList`
- `parse_forbidden_word_list(node) -> ForbiddenWordList`
- `memo_shape_from_attributes(attrs) -> MemoShape`
- `parse_memo_shape(node) -> MemoShape`
- `parse_memo_properties(node) -> MemoProperties`
- `parse_ref_list(node) -> RefList`
- `parse_header_element(node) -> Header`
***
## `hwpx.oxml.utils`
###
- `local_name(node) -> str`
- .
- `parse_int(value, allow_none=True) -> Optional[int]`
- , `None` .
- `parse_bool(value, default=None) -> Optional[bool]`
- / , .
- `text_or_none(node) -> Optional[str]`
- , `None` .
- `coerce_xml_source(source) -> tuple[etree._Element, etree._ElementTree]`
- XML , , `lxml` . .
***
## `hwpx.oxml.schema`
###
- `load_schema(path) -> etree.XMLSchema`
- XML . (import) (resolver) XSD .
***
## `hwpx.oxml.parser`
###
- `element_to_model(node) -> object`
- , `GenericElement` .
- `parse_header_xml(source, schema_path=None, schema=None) -> header.Header`
- XML , , .
- `parse_section_xml(source, schema_path=None, schema=None) -> body.Section`
- `parse_header_xml` .
***
## `hwpx.oxml.document`
###
- `_serialize_xml(element) -> bytes`: `ElementTree` XML UTF-8 .
- `_paragraph_id()`, `_object_id()`, `_memo_id()`: , , .
- `_create_paragraph_element(text, ...)`: .
- `_element_local_name(node)`: .
- `_distribute_size(total, parts)`: .
- `_default_cell_attributes(border_fill_id_ref)`: .
- `_default_sublist_attributes()`: `` .
- `_default_cell_paragraph_attributes()`: .
- `_default_cell_margin_attributes()`: 0 .
- `_get_int_attr(element, name, default=0)`: , .
- `_char_properties_from_header(element)`: .
###
- `PageSize`: , , , .
- `PageMargins`: , , , , , , .
- `SectionStartNumbering`: .
- `DocumentNumbering`: .
- `RunStyle`: :
- `text_color()`: ( ) .
- `underline_type()`: .
- `underline_color()`: .
- `matches(...)`: / (predicate).
### `HwpxOxmlSectionHeaderFooter`
- `id`: / dirty getter/setter .
- `apply_page_type`: / (//) .
- `text`: / .
- `_initial_sublist_attributes()` / `_ensure_text_element()`: .
### `HwpxOxmlSectionProperties`
- `_page_pr_element(create=False)` / `_margin_element(create=False)`: .
- `page_size`: `PageSize` .
- `set_page_size(...)`: dirty .
- `page_margins`: `PageMargins` .
- `set_page_margins(...)`: .
- `start_numbering`: `` `SectionStartNumbering` .
- `set_start_numbering(...)`: , `` .
- `headers`, `footers`: / .
- `get_header(page_type="BOTH")` / `get_footer(...)`: / .
- `set_header_text(text, ...)` / `set_footer_text(...)`: / . ``/`` ID .
- `remove_header(page_type="BOTH")` / `remove_footer(...)`: / , apply .
### `HwpxOxmlRun`
- `char_pr_id_ref`: , XML dirty setter .
- `text`: .
- `style`: `RunStyle` .
- `replace_text(search, replacement, count=None)`: .
- `remove()`: .
- `bold`, `italic`, `underline`: .
- `_current_format_flags()`, `_apply_format_change(...)`, `_plain_text_nodes()`, `_ensure_plain_text_node()`: .
### `HwpxOxmlMemoGroup`
- `memos`: `HwpxOxmlMemo` .
- `add_memo(...)`: , , .
- `_cleanup()`: .
### `HwpxOxmlMemo`
- `id`, `memo_shape_id_ref`: XML setter .
- `attributes`: .
- `set_attribute(name, value)`: .
- `paragraphs`: .
- `text`: . setter `set_text()` .
- `set_text(value, char_pr_id_ref=None)`: .
- `_infer_char_pr_id_ref()`: .
- `remove()`: .
### `HwpxOxmlInlineObject`
- `tag`: .
- `attributes`: .
- `get_attribute(name)` / `set_attribute(name, value)`: dirty .
### `HwpxOxmlTableCell`
- `address`: `` `(, )` .
- `span`: `` `( , )` .
- `set_span(row_span, col_span)`: dirty .
- `width`, `height`: `` .
- `set_size(width=None, height=None)`: 0 .
- `text`: . setter , `` / .
- `remove()`: .
- `_addr_element()`, `_span_element()`, `_size_element()`, `_ensure_text_element()`: XML .
### `HwpxOxmlTableRow`
- `cells`: `HwpxOxmlTableCell` .
### `HwpxTableGridPosition`
- `row`, `column`: .
- `cell`: `HwpxOxmlTableCell` .
- `anchor`: `(row, column)` .
- `span`: `row_span`, `col_span` .
- `is_anchor`: .
- `row_span`, `col_span`: .
### `HwpxOxmlTable`
- `create(rows, cols, ...)`: , , .
- `mark_dirty()`: .
- `row_count`, `column_count`: / XML .
- `rows`: `HwpxOxmlTableRow` .
- `cell(row_index, col_index)`: .
- `iter_grid()`: `HwpxTableGridPosition` .
- `get_cell_map()`: `row_count x column_count` 2 . `HwpxTableGridPosition`.
- `set_cell_text(row_index, col_index, text, logical=False, split_merged=False)`: . `logical=True` , `split_merged=True` . / .
- `split_merged_cell(row_index, col_index)`: , .
- `merge_cells(start_row, ...)`: , , , .
### `HwpxOxmlParagraph`
- `runs`: `HwpxOxmlRun` .
- `text`: . setter .
- `add_run(text="", ...)`: , , .
- `remove()`: . `ValueError` .
- `tables`: `HwpxOxmlTable` .
- `add_table(...)`, `add_line(...)`, `add_rectangle(...)`, `add_ellipse(...)`: (, ) . .
- `add_shape(...)`, `add_control(...)`: . `UserWarning` , .
- `para_pr_id_ref`, `style_id_ref`, `char_pr_id_ref`: setter .
- `_run_elements()`, `_ensure_run()`, `_create_run_for_object()`: .
### `HwpxOxmlSection`
- `properties`: `` `HwpxOxmlSectionProperties` .
- `element`: `Element` .
- `document`: `HwpxOxmlDocument` . `attach_document()` .
- `paragraphs`: .
- `memo_group`: `HwpxOxmlMemoGroup` .
- `memos`: .
- `add_memo(...)`: `HwpxOxmlMemoGroup.add_memo()` .
- `add_paragraph(text="", ...)`: .
- `remove_paragraph(paragraph_or_index)`: . `ValueError` .
- `mark_dirty()`, `dirty`, `reset_dirty()`: .
- `to_bytes() -> bytes`: `_serialize_xml()` .
### `HwpxOxmlHeader`
- `element`: `Element` .
- `document`: . `attach_document()` .
- `ensure_char_property(...)`: `predicate` `` . ( ), `modifier` , ID , `itemCnt` , .
- `begin_numbering`: `` `DocumentNumbering` .
- `set_begin_numbering(...)`: `` .
- `memo_shapes`: .
- `memo_shape(memo_shape_id_ref)`: ID .
- `dirty`, `mark_dirty()`, `reset_dirty()`: .
- `to_bytes()`: `_serialize_xml()` .
- .
### `HwpxOxmlDocument`
- `from_package(package)`: `HwpxPackage` , XML , XML .
- `manifest`: .
- `sections`, `headers`: .
- `char_properties`: ID `RunStyle` , .
- `char_property(char_pr_id_ref)`: ID `RunStyle` .
- `ensure_run_style(...)`: , , , .
- `memo_shapes`: .
- `memo_shape(memo_shape_id_ref)`: ID .
- `paragraphs`: .
- `add_paragraph(...)`: `section` `section_index` . .
- `remove_paragraph(paragraph_or_index, section=None, section_index=None)`: . .
- `add_section(after=None) -> HwpxOxmlSection`: . manifest `` `` .
- `remove_section(section_or_index)`: . , `ValueError` .
- `serialize() -> dict[str, bytes]`: (dirty) / . manifest .
- `reset_dirty()`: (clean) .
- .
***
## `hwpx.opc.package`
###
- `HwpxPackageError`: .
- `HwpxStructureError`: HWPX .
###
- `RootFile`: `META-INF/container.xml` `` , `ensure_exists(files)` .
### `VersionInfo`
- `from_bytes(data)`: `version.xml` XML .
- `_collect_namespaces(data)`: `iterparse()` .
- `_extract_declaration(data)`: XML .
- `attributes`: .
- `get(key, default=None)`: .
- `set(key, value)`: dirty .
- `tag`: .
- `to_bytes()`: , XML .
- `dirty`: .
- `mark_clean()`: `version.xml` dirty .
### `HwpxPackage`
####
- `open(pkg_file)`: zip , , `container.xml` `version.xml` , .
- `_parse_container(data)`: `` `HwpxStructureError` .
- `_parse_version(data)`: `VersionInfo` .
- `_validate_structure()`: , `Contents` .
####
- `mimetype`: mimetype .
- `rootfiles`: `container.xml` `RootFile` .
- `iter_rootfiles()`: .
- `main_content`: HWPML , .
- `version_info`: `VersionInfo` .
####
- `read(path)`: , `HwpxPackageError` .
- `write(path, data)`: , .
- `delete(path)`: .
- `_normalize_path(path)`: .
- `files()`: .
- `save(pkg_file)`: . `mimetype` , `version.xml` , editor-open safety .
- raw ZIP writer . safety public , save .
***
## `hwpx.tools.text_extractor`
###
- `DEFAULT_NAMESPACES`: HWPX XML .
- `_SECTION_PATTERN`: XML (`Contents/section*.xml`) .
- `_OBJECT_CONTAINERS`: .
###
- `_ObjectBehavior`, `HighlightBehavior`, ...: .
###
- `AnnotationOptions`: , , , . `highlight_start`, `note_inline_format` .
- `SectionInfo`: , , .
- `ParagraphInfo`: , , , , , . :
- `tag`: .
- `ancestors`: .
- `is_nested`: .
- `text(...)`: `TextExtractor.paragraph_text()` .
### `TextExtractor`
- `__init__(source, ...)`: (, zip , `ZipFile` ) , , .
- `open()`: `ZipFile` , .
- `close()`: .
- `__enter__()`, `__exit__()`: .
- `iter_sections()`: XML (yield).
- `iter_paragraphs(section, ...)`: `ParagraphInfo` . (`include_nested=True`) .
- `iter_document_paragraphs(...)`: .
- `paragraph_text(paragraph, ...)`: . ( , , ) .
- `_handle_object(...)`, `_handle_note(...)` : `paragraph_text()` , , .
- `extract_text(paragraph_separator="\n", ...)`: .
- `_iter_section_files(archive)`: `content.hpf` .
###
- `_resolve_note_text(...)`: `subList` .
- `_resolve_control_nested_text(...)`: .
- `_resolve_hyperlink_target(...)`: `fieldBegin` .
- `strip_namespace(tag)`: .
- `tag_matches(...)`: .
- `build_parent_map(root)`: .
- `describe_element_path(...)`: XPath .
- `_section_sort_key(name)`: .
***
## `hwpx.tools.object_finder`
###
- `AttrMatcher`: , , .
- `FoundElement`: , , . :
- `tag`: .
- `hierarchy`: .
- `text`: `element.text` .
- `get(name, ...)`: .
- `AnnotationMatch`: `ObjectFinder.iter_annotations()` , , , .
### `ObjectFinder`
- `__init__(source, ...)`: .
- `iter(tag=None, attrs=None, ...)`: , , XPath `FoundElement` (yield) . `limit` .
- `find_first(...)`: `iter()` `limit=1` `None` .
- `find_all(...)`: `iter()` .
- `iter_annotations(kinds=None, ...)`: , , , , `AnnotationOptions` `AnnotationMatch` .
- `_format_note_annotation(...)`: .
- `_match_attributes(element, expected)`: `iter()` .
***
## `hwpx.tools.validator`
###
- `DocumentSchemas`: XML .
- `ValidationIssue`: . , , `__str__` .
- `ValidationReport`: , . `ok` ( ) .
###
- `load_default_schemas(schema_dir=None)`: XSD , . `` , OWPML .
- `_iter_parts(document)`: `HwpxDocument` `( , XML , )` .
- `_issues_from_error(part_name, exc)`: `lxml` `ValidationIssue` .
- `validate_document(source, ...)`: , , .
***
## `hwpx.oxml.namespaces`
OWPML URI Clark .
###
| | | |
|------|-----|------|
| `HP_NS` | `http://www.hancom.co.kr/hwpml/2011/paragraph` | URI |
| `HP` | `{http://www.hancom.co.kr/hwpml/2011/paragraph}` | Clark |
| `HH_NS` | `http://www.hancom.co.kr/hwpml/2011/head` | URI |
| `HH` | `{http://www.hancom.co.kr/hwpml/2011/head}` | Clark |
| `HC_NS` | `http://www.hancom.co.kr/hwpml/2011/core` | URI |
| `HC` | `{http://www.hancom.co.kr/hwpml/2011/core}` | Clark |
| `HS_NS` | `http://www.hancom.co.kr/hwpml/2011/section` | URI |
| `HS` | `{http://www.hancom.co.kr/hwpml/2011/section}` | Clark |
| `HP_2016_NS` | `http://www.hancom.co.kr/hwpml/2016/paragraph` | 2016 |
| `HH_2016_NS` | `http://www.hancom.co.kr/hwpml/2016/head` | 2016 |
| `HC_2016_NS` | `http://www.hancom.co.kr/hwpml/2016/core` | 2016 |
***
## (`hwpx.__init__`)
- `main(argv=None)`: , , . 0, 0 .
***
## `hwpx.__init__`
(re-exports) :
- `hwpx.tools.text_extractor` `DEFAULT_NAMESPACES`, `ParagraphInfo`, `SectionInfo`, `TextExtractor`
- `hwpx.tools.object_finder` `FoundElement`, `ObjectFinder`
## Proposal presets 5.0
`hwpx.presets` 5.0 `hwpx_automation.office.authoring.presets`
. [5.0 ](migration-5.0.md) .