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)

  • 보류 중인 업데이트를 영구 저장하고 대상 경로/스트림/바이트를 반환합니다. 대상이 제공되지 않으면 원본 소스를 재사용하고, 그렇지 않으면 요청된 파일 시스템 위치나 스트림에 zip 아카이브를 작성합니다.

• _write_to_stream(stream) 및 _write_archive(archive)

  • save() 메서드를 위해 zip 직렬화를 처리하는 내부 유틸리티입니다.

---

모듈 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

  • 대상 섹션에 단락을 추가합니다. 선택적으로 단락 및 런 서식 참조를 재정의하거나 추가 단락 속성을 주입할 수 있습니다.

• add_table(rows, cols, ...) -> HwpxOxmlTable

  • 단락을 삽입하고 그 안에 표 인라인 객체를 생성한 후, 표 래퍼를 반환합니다. border_fill_id_ref를 생략하면 헤더 참조 목록에 기본 실선 borderFill을 생성하고 표와 셀에 자동으로 연결합니다.

• add_shape(shape_type, ...) -> HwpxOxmlInlineObject

  • 새 단락에 태그 이름을 사용하여 인라인 그리기 요소를 삽입합니다.

• add_control(...) -> HwpxOxmlInlineObject

  • 새 단락에 인라인 컨트롤 객체(예: 양식 컨트롤)를 삽입합니다.

영속성(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.oxml.common

클래스 GenericElement

• 특화된 파서가 없는 엘리먼트를 나타내는 데이터클래스입니다.

함수

• parse_generic_element(node) -> GenericElement

  • XML 노드와 그 자식들을 재귀적으로 GenericElement 구조로 변환하며 속성과 텍스트를 보존합니다.

---

모듈 hwpx.oxml.body

데이터 클래스

• TextSpan

  • 텍스트 런, 수집된 마크 엘리먼트 및 속성을 캡처합니다.

• Run

  • 글자 참조, 중첩된 컨트롤, 인라인 객체 및 추가 자식을 포함하는 <hp:run>을 나타냅니다.

• Paragraph

  • 런 컬렉션과 속성을 포함하는 <hp:p> 단락을 나타냅니다.

• Section

  • 단락과 추가 노드를 포함하는 <hs:sec> 문서 섹션을 나타냅니다.

파싱 함수

• parse_text_span(node) -> TextSpan

  • <hp:t> 엘리먼트로부터 TextSpan을 빌드하며, 중첩된 마크를 보존합니다.

• parse_run_element(node) -> Run

  • <hp:run> 엘리먼트를 Run 데이터클래스로 변환하며, 컨트롤 및 인라인 객체와 같은 자식 엘리먼트를 분류합니다.

• parse_paragraph_element(node) -> Paragraph

  • <hp:p> 엘리먼트를 Paragraph 데이터클래스로 변환합니다.

• parse_section_element(node) -> Section

  • <hs:sec> 엘리먼트를 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(): <hp:subList> 컨테이너의 기본 속성을 제공합니다.

• _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: <hp:startNum>의 SectionStartNumbering 스냅샷을 반환하는 프로퍼티입니다.

• set_start_numbering(...): 번호 매기기 카운터와 페이지 시작 동작을 수정하며, <hp:startNum> 엘리먼트가 없으면 생성합니다.

• headers, footers: 기존 머리글/바닥글 정의에 대한 래퍼를 반환하는 프로퍼티입니다.

• get_header(page_type="BOTH") / get_footer(...): 지정된 페이지 유형의 기존 머리글/바닥글 래퍼를 가져옵니다.

• set_header_text(text, ...) / set_footer_text(...): 요청된 페이지 유형에 대한 머리글/바닥글이 있는지 확인하고 텍스트 내용을 교체합니다. 동시에 <hp:headerApply>/<hp:footerApply> 노드와 마스터 페이지 참조를 동일한 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: <hp:cellAddr>에서 파생된 (행, 열) 튜플을 반환하는 프로퍼티입니다.

• span: <hp:cellSpan>의 (행 병합, 열 병합) 값을 반환하는 프로퍼티입니다.

• set_span(row_span, col_span): 병합 속성을 업데이트하고 표를 dirty로 표시합니다.

• width, height: <hp:cellSz>에서 캐시된 셀 크기를 노출하는 프로퍼티입니다.

• set_size(width=None, height=None): 크기 속성을 0 또는 그 이상으로 업데이트합니다.

• text: 셀 내부의 첫 번째 텍스트 노드를 반환하는 프로퍼티입니다. setter는 텍스트를 할당하기 전에 중첩된 단락 구조를 보장하고, <hp:lineSegArray>와 같은 줄 배치 캐시를 제거하여 한/글이 줄바꿈을 다시 계산하도록 합니다.

• 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="", ...): 새 런을 추가하고, 선택적으로 소유 문서를 통해 일치하는 글자 스타일을 생성한 후, 래퍼를 반환합니다.

• tables: 단락 내에 포함된 HwpxOxmlTable 래퍼를 반환하는 프로퍼티입니다.

• add_table(...), add_shape(...), add_control(...): 적절한 런을 생성하여 인라인 객체(표, 도형, 컨트롤)를 삽입하고 래퍼 객체를 반환합니다.

• para_pr_id_ref, style_id_ref, char_pr_id_ref: 단락 수준의 서식 재정의를 허용하는 setter가 있는 프로퍼티입니다.

• _run_elements(), _ensure_run(), _create_run_for_object(): 위 작업들을 위해 런 생성 및 접근을 관리하는 내부 헬퍼입니다.

클래스 HwpxOxmlSection

• properties: <hp:secPr> 계층이 필요할 때 이를 생성하며 HwpxOxmlSectionProperties 래퍼를 반환하는 프로퍼티입니다.

• element: 원시 섹션 Element를 반환하는 프로퍼티입니다.

• document: 소유 HwpxOxmlDocument를 참조하는 프로퍼티입니다. attach_document()는 섹션을 문서 인스턴스와 연결합니다.

• paragraphs: 문서 순서대로 단락 래퍼를 반환하는 프로퍼티입니다.

• memo_group: 메모 그룹이 존재할 때 HwpxOxmlMemoGroup 래퍼를 반환하는 프로퍼티입니다.

• memos: 섹션의 메모 래퍼를 반환하는 프로퍼티입니다.

• add_memo(...): 메모 그룹이 있는지 확인한 후 HwpxOxmlMemoGroup.add_memo()에 위임하는 편의 메서드입니다.

• add_paragraph(text="", ...): 선택적 서식 재정의와 함께 단락 엘리먼트를 추가하고 그 래퍼를 반환합니다.

• mark_dirty(), dirty, reset_dirty(): 섹션을 저장해야 하는지 여부를 추적합니다.

• to_bytes() -> bytes: _serialize_xml()을 사용하여 섹션 엘리먼트를 직렬화합니다.

클래스 HwpxOxmlHeader

• element: 원시 헤더 Element를 반환하는 프로퍼티입니다.

• document: 소유 문서를 참조하는 프로퍼티입니다. attach_document()로 할당합니다.

• ensure_char_property(...): predicate와 일치하는 <hh:charPr> 항목이 있는지 확인합니다. 일치하는 항목이 없으면 기존 항목을 복제(또는 빈 항목 생성)하고, modifier를 적용하며, 고유 ID를 할당하고, itemCnt를 업데이트한 후, 문서의 글자 스타일 캐시를 무효화합니다.

• begin_numbering: <hh:beginNum>에서 생성된 DocumentNumbering 스냅샷을 반환하는 프로퍼티입니다.

• set_begin_numbering(...): 음수가 아닌 카운터 값으로 <hh:beginNum> 엘리먼트를 업데이트하거나 생성합니다.

• 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를 사용하여 대상 섹션을 선택하여 단락을 추가하도록 섹션에 위임합니다. 기본값은 마지막 섹션입니다.

• serialize() -> dict[str, bytes]: 변경된(dirty) 섹션/헤더에 대한 업데이트된 파트 페이로드 딕셔너리를 반환합니다.

• reset_dirty(): 저장 후 모든 섹션과 헤더를 깨끗한(clean) 상태로 표시합니다.

• 내부 헬퍼는 캐시된 런 스타일을 유지 관리합니다.

---

모듈 hwpx.opc.package

예외

• HwpxPackageError: 패키지 조작 오류에 대한 기본 예외입니다.

• HwpxStructureError: HWPX 패키지의 필수 구조 구성 요소가 없거나 일치하지 않을 때 발생합니다.

데이터 클래스

• RootFile: META-INF/container.xml 내의 <rootfile> 항목을 나타내며, 참조된 경로가 아카이브에 있는지 확인하는 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): <rootfile> 선언을 추출하고 필수 속성을 강제하며 오류 시 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을 직렬화하며, 구조를 검증하고, 다른 파일들은 deflate 압축으로 씁니다.

• _write_mimetype(zf): OPC 사양에 따라 ZIP_STORED를 사용하여 mimetype 항목을 쓰는 내부 헬퍼입니다.

---

모듈 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 파일을 로드하며, 스키마 디렉토리가 없을 때 예외를 발생시킵니다.

• _iter_parts(document): HwpxDocument의 모든 헤더와 섹션에 대해 (파트 이름, XML 바이트, 헤더 여부)를 순회하는 내부 헬퍼입니다.

• _issues_from_error(part_name, exc): lxml 유효성 검사 오류를 ValidationIssue 인스턴스로 정규화합니다.

• validate_document(source, ...): 문서를 열고, 제공되지 않은 경우 기본 스키마를 로드하며, 각 헤더 및 섹션 파트를 적절한 파서로 검증하고 이슈를 집계합니다.

• main(argv=None): 인자를 파싱하고, 문서를 검증하며, 결과를 출력하는 명령줄 진입점입니다. 성공 시 0을, 이슈 발생 시 0이 아닌 값을 반환합니다.

---

모듈 hwpx.__init__

이 패키지는 편의를 위해 다음과 같은 재내보내기(re-exports)를 노출합니다:

• hwpx.tools.text_extractor 모듈의 DEFAULT_NAMESPACES, ParagraphInfo, SectionInfo, TextExtractor

• hwpx.tools.object_finder 모듈의 FoundElement, ObjectFinder