python-hwpx 1.2__tar.gz → 1.3__tar.gz

python-hwpx-1.3/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.1
+Name: python-hwpx
+Version: 1.3
+Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
+Author: python-hwpx Maintainers
+License: Non-Commercial License
+Project-URL: Homepage, https://github.com/airmang/python-hwpx
+Project-URL: Documentation, https://github.com/airmang/python-hwpx/tree/main/docs
+Project-URL: Issues, https://github.com/airmang/python-hwpx/issues
+Keywords: hwp,hwpx,hancom,opc,xml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lxml<6,>=4.9
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+
+# python-hwpx
+
+`python-hwpx`는 Hancom HWPX 문서를 읽고, 편집하고, 자동화 스크립트로 재가공하기 위한 파이썬 도구 모음입니다. Open Packaging Convention(OPC) 컨테이너를 검사하는 저수준 도구부터 문단·표·메모를 쉽게 다루는 고수준 API, 텍스트 추출과 객체 검색 유틸리티까지 하나로 제공합니다.
+
+## 특징 요약
+
+- **패키지 로딩과 검증** – `hwpx.opc.package.HwpxPackage`로 `mimetype`, `container.xml`, `version.xml`을 확인하며 모든 파트를 메모리에 적재합니다.
+- **문서 편집 API** – `hwpx.document.HwpxDocument`는 문단과 표, 메모, 헤더 속성을 파이썬 객체로 노출하고 새 콘텐츠를 손쉽게 추가합니다. 섹션 머리말·꼬리말을 수정하면 `<hp:headerApply>`/`<hp:footerApply>`와 마스터 페이지 링크도 함께 갱신합니다.
+- **타입이 지정된 본문 모델** – `hwpx.oxml.body`는 표·컨트롤·인라인 도형·변경 추적 태그를 데이터 클래스에 매핑하고, `HwpxOxmlParagraph.model`/`HwpxOxmlRun.model`로 이를 조회·수정한 뒤 XML로 되돌릴 수 있도록 지원합니다.
+- **메모와 필드 앵커** – `add_memo_with_anchor()`로 메모를 생성하면서 MEMO 필드 컨트롤을 자동 삽입해 한/글에서 바로 표시되도록 합니다.
+- **헤더 참조 목록 탐색** – 글머리표, 문단 속성, 스타일, 변경 추적 항목, 작성자 정보를 데이터클래스로 파싱하고 `document.bullets`·`document.styles` 같은 조회 헬퍼로 ID 기반 검색을 단순화했습니다.
+- **스타일 기반 텍스트 치환** – 런 서식(색상, 밑줄, `charPrIDRef`)으로 필터링해 텍스트를 선택적으로 교체하거나 삭제합니다. 하이라이트
+  마커나 태그로 분리된 문자열도 서식을 유지한 채 치환합니다.
+- **텍스트 추출 파이프라인** – `hwpx.tools.text_extractor.TextExtractor`는 하이라이트, 각주, 컨트롤을 원하는 방식으로 표현하며 문단 텍스트를 반환합니다.
+- **풍부한 문서** – 빠른 시작, 50개의 사용 패턴, 설치/FAQ/스키마 개요를 Sphinx 기반 웹 문서로 제공합니다.
+
+## 설치
+
+PyPI에서 최신 버전을 바로 설치할 수 있습니다.
+
+```bash
+python -m pip install python-hwpx
+```
+
+개발 버전이나 문서 빌드를 직접 수정하려면 저장소를 클론한 뒤 편집 가능한 설치를 사용하세요.
+
+```bash
+git clone https://github.com/<your-org>/python-hwpx.git
+cd python-hwpx
+python -m pip install -e .[dev]
+```
+
+Sphinx 문서는 `docs/` 아래에 있으며, `python -m pip install -r docs/requirements.txt` 후 `make -C docs html`로 로컬 미리보기가 가능합니다.
+
+## 5분 안에 맛보기
+
+```python
+from io import BytesIO
+
+from hwpx.document import HwpxDocument
+from hwpx.templates import blank_document_bytes
+
+# 1) 빈 템플릿으로 문서 열기
+source = BytesIO(blank_document_bytes())
+document = HwpxDocument.open(source)
+print("sections:", len(document.sections))
+
+# 2) 문단과 표, 메모 추가
+section = document.sections[0]
+paragraph = document.add_paragraph("자동 생성한 문단", section=section)
+table = document.add_table(rows=2, cols=2, section=section)
+table.set_cell_text(0, 0, "항목")
+table.set_cell_text(0, 1, "값")
+table.set_cell_text(1, 0, "문단 수")
+table.set_cell_text(1, 1, str(len(document.paragraphs)))
+document.add_memo_with_anchor("배포 전 검토", paragraph=paragraph, memo_shape_id_ref="0")
+
+# 3) 다른 이름으로 저장
+document.save("output/example.hwpx")
+```
+
+더 많은 실전 패턴은 [빠른 시작](docs/quickstart.md)과 [사용 가이드](docs/usage.md)의 "빠른 예제 모음"에서 확인할 수 있습니다.
+
+## 문서
+ [사용법](https://airmang.github.io/python-hwpx/)
+
+## 예제와 도구
+
+- `examples/` 디렉터리는 텍스트 추출, 객체 검색, QA 체크리스트 생성 예제를 제공합니다. PyPI 패키지에는 포함되지 않으므로 필요하면 저장소를 클론하거나 웹 문서의 코드 스니펫을 활용하세요.
+- `hwpx.templates.blank_document_bytes()`는 추가 리소스 없이 빈 HWPX 문서를 만들 수 있는 내장 템플릿을 제공합니다.
+
+## 알려진 제약
+
+- `add_shape()`/`add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않으므로, 복잡한 개체를 추가할 때는 편집기에서 열어 검증해 주세요.
+
+## 기여하기
+
+버그 리포트와 개선 제안은 언제나 환영합니다. 개발 환경 설정과 테스트 방법은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.
+
+## 라이선스와 연락처
+
+- 라이선스: [LICENSE](LICENSE)
+- 문의: 이슈 트래커 또는 kokyuhyun@hotmail.com

python-hwpx-1.3/README.md

@@ -0,0 +1,83 @@
+# python-hwpx
+
+`python-hwpx`는 Hancom HWPX 문서를 읽고, 편집하고, 자동화 스크립트로 재가공하기 위한 파이썬 도구 모음입니다. Open Packaging Convention(OPC) 컨테이너를 검사하는 저수준 도구부터 문단·표·메모를 쉽게 다루는 고수준 API, 텍스트 추출과 객체 검색 유틸리티까지 하나로 제공합니다.
+
+## 특징 요약
+
+- **패키지 로딩과 검증** – `hwpx.opc.package.HwpxPackage`로 `mimetype`, `container.xml`, `version.xml`을 확인하며 모든 파트를 메모리에 적재합니다.
+- **문서 편집 API** – `hwpx.document.HwpxDocument`는 문단과 표, 메모, 헤더 속성을 파이썬 객체로 노출하고 새 콘텐츠를 손쉽게 추가합니다. 섹션 머리말·꼬리말을 수정하면 `<hp:headerApply>`/`<hp:footerApply>`와 마스터 페이지 링크도 함께 갱신합니다.
+- **타입이 지정된 본문 모델** – `hwpx.oxml.body`는 표·컨트롤·인라인 도형·변경 추적 태그를 데이터 클래스에 매핑하고, `HwpxOxmlParagraph.model`/`HwpxOxmlRun.model`로 이를 조회·수정한 뒤 XML로 되돌릴 수 있도록 지원합니다.
+- **메모와 필드 앵커** – `add_memo_with_anchor()`로 메모를 생성하면서 MEMO 필드 컨트롤을 자동 삽입해 한/글에서 바로 표시되도록 합니다.
+- **헤더 참조 목록 탐색** – 글머리표, 문단 속성, 스타일, 변경 추적 항목, 작성자 정보를 데이터클래스로 파싱하고 `document.bullets`·`document.styles` 같은 조회 헬퍼로 ID 기반 검색을 단순화했습니다.
+- **스타일 기반 텍스트 치환** – 런 서식(색상, 밑줄, `charPrIDRef`)으로 필터링해 텍스트를 선택적으로 교체하거나 삭제합니다. 하이라이트
+  마커나 태그로 분리된 문자열도 서식을 유지한 채 치환합니다.
+- **텍스트 추출 파이프라인** – `hwpx.tools.text_extractor.TextExtractor`는 하이라이트, 각주, 컨트롤을 원하는 방식으로 표현하며 문단 텍스트를 반환합니다.
+- **풍부한 문서** – 빠른 시작, 50개의 사용 패턴, 설치/FAQ/스키마 개요를 Sphinx 기반 웹 문서로 제공합니다.
+
+## 설치
+
+PyPI에서 최신 버전을 바로 설치할 수 있습니다.
+
+```bash
+python -m pip install python-hwpx
+```
+
+개발 버전이나 문서 빌드를 직접 수정하려면 저장소를 클론한 뒤 편집 가능한 설치를 사용하세요.
+
+```bash
+git clone https://github.com/<your-org>/python-hwpx.git
+cd python-hwpx
+python -m pip install -e .[dev]
+```
+
+Sphinx 문서는 `docs/` 아래에 있으며, `python -m pip install -r docs/requirements.txt` 후 `make -C docs html`로 로컬 미리보기가 가능합니다.
+
+## 5분 안에 맛보기
+
+```python
+from io import BytesIO
+
+from hwpx.document import HwpxDocument
+from hwpx.templates import blank_document_bytes
+
+# 1) 빈 템플릿으로 문서 열기
+source = BytesIO(blank_document_bytes())
+document = HwpxDocument.open(source)
+print("sections:", len(document.sections))
+
+# 2) 문단과 표, 메모 추가
+section = document.sections[0]
+paragraph = document.add_paragraph("자동 생성한 문단", section=section)
+table = document.add_table(rows=2, cols=2, section=section)
+table.set_cell_text(0, 0, "항목")
+table.set_cell_text(0, 1, "값")
+table.set_cell_text(1, 0, "문단 수")
+table.set_cell_text(1, 1, str(len(document.paragraphs)))
+document.add_memo_with_anchor("배포 전 검토", paragraph=paragraph, memo_shape_id_ref="0")
+
+# 3) 다른 이름으로 저장
+document.save("output/example.hwpx")
+```
+
+더 많은 실전 패턴은 [빠른 시작](docs/quickstart.md)과 [사용 가이드](docs/usage.md)의 "빠른 예제 모음"에서 확인할 수 있습니다.
+
+## 문서
+ [사용법](https://airmang.github.io/python-hwpx/)
+
+## 예제와 도구
+
+- `examples/` 디렉터리는 텍스트 추출, 객체 검색, QA 체크리스트 생성 예제를 제공합니다. PyPI 패키지에는 포함되지 않으므로 필요하면 저장소를 클론하거나 웹 문서의 코드 스니펫을 활용하세요.
+- `hwpx.templates.blank_document_bytes()`는 추가 리소스 없이 빈 HWPX 문서를 만들 수 있는 내장 템플릿을 제공합니다.
+
+## 알려진 제약
+
+- `add_shape()`/`add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않으므로, 복잡한 개체를 추가할 때는 편집기에서 열어 검증해 주세요.
+
+## 기여하기
+
+버그 리포트와 개선 제안은 언제나 환영합니다. 개발 환경 설정과 테스트 방법은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.
+
+## 라이선스와 연락처
+
+- 라이선스: [LICENSE](LICENSE)
+- 문의: 이슈 트래커 또는 kokyuhyun@hotmail.com

{python-hwpx-1.2 → python-hwpx-1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "1.2"
+version = "1.3"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "Non-Commercial License" }

{python-hwpx-1.2 → python-hwpx-1.3}/src/hwpx/document.py

@@ -10,6 +10,7 @@ from os import PathLike
 from typing import BinaryIO, Iterator, List, Tuple
 
 from .oxml import (
+    Bullet,
     HwpxOxmlDocument,
     HwpxOxmlHeader,
     HwpxOxmlInlineObject,
@@ -17,9 +18,14 @@ from .oxml import (
     HwpxOxmlParagraph,
     HwpxOxmlRun,
     HwpxOxmlSection,
+    HwpxOxmlSectionHeaderFooter,
     HwpxOxmlTable,
     MemoShape,
+    ParagraphProperty,
     RunStyle,
+    Style,
+    TrackChange,
+    TrackChangeAuthor,
 )
 from .package import HwpxPackage
 from .templates import blank_document_bytes
@@ -94,6 +100,65 @@ class HwpxDocument:
 
         return self._root.memo_shape(memo_shape_id_ref)
 
+    @property
+    def bullets(self) -> dict[str, Bullet]:
+        """Return bullet definitions declared in header reference lists."""
+
+        return self._root.bullets
+
+    def bullet(self, bullet_id_ref: int | str | None) -> Bullet | None:
+        """Return the bullet definition referenced by *bullet_id_ref*."""
+
+        return self._root.bullet(bullet_id_ref)
+
+    @property
+    def paragraph_properties(self) -> dict[str, ParagraphProperty]:
+        """Return paragraph property definitions declared in headers."""
+
+        return self._root.paragraph_properties
+
+    def paragraph_property(
+        self, para_pr_id_ref: int | str | None
+    ) -> ParagraphProperty | None:
+        """Return the paragraph property referenced by *para_pr_id_ref*."""
+
+        return self._root.paragraph_property(para_pr_id_ref)
+
+    @property
+    def styles(self) -> dict[str, Style]:
+        """Return style definitions available in the document."""
+
+        return self._root.styles
+
+    def style(self, style_id_ref: int | str | None) -> Style | None:
+        """Return the style definition referenced by *style_id_ref*."""
+
+        return self._root.style(style_id_ref)
+
+    @property
+    def track_changes(self) -> dict[str, TrackChange]:
+        """Return tracked change metadata declared in the headers."""
+
+        return self._root.track_changes
+
+    def track_change(self, change_id_ref: int | str | None) -> TrackChange | None:
+        """Return tracked change metadata referenced by *change_id_ref*."""
+
+        return self._root.track_change(change_id_ref)
+
+    @property
+    def track_change_authors(self) -> dict[str, TrackChangeAuthor]:
+        """Return tracked change author metadata declared in the headers."""
+
+        return self._root.track_change_authors
+
+    def track_change_author(
+        self, author_id_ref: int | str | None
+    ) -> TrackChangeAuthor | None:
+        """Return tracked change author details referenced by *author_id_ref*."""
+
+        return self._root.track_change_author(author_id_ref)
+
     @property
     def memos(self) -> List[HwpxOxmlMemo]:
         """Return all memo entries declared in every section."""
@@ -389,11 +454,17 @@ class HwpxDocument:
                 remaining = limit - replacements
                 if remaining <= 0:
                     break
-            replacements += run.replace_text(
+            original_char_pr = run.char_pr_id_ref
+            replaced_here = run.replace_text(
                 search,
                 replacement,
                 count=remaining,
             )
+            if replaced_here and original_char_pr is not None:
+                # Ensure the run retains its original formatting reference even
+                # if XML nodes were rewritten during substitution.
+                run.char_pr_id_ref = original_char_pr
+            replacements += replaced_here
             if limit is not None and replacements >= limit:
                 break
         return replacements
@@ -533,6 +604,80 @@ class HwpxDocument:
             char_pr_id_ref=char_pr_id_ref,
         )
 
+    def set_header_text(
+        self,
+        text: str,
+        *,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        page_type: str = "BOTH",
+    ) -> HwpxOxmlSectionHeaderFooter:
+        """Ensure the requested section contains a header for *page_type* and set its text."""
+
+        target_section = section
+        if target_section is None and section_index is not None:
+            target_section = self._root.sections[section_index]
+        if target_section is None:
+            if not self._root.sections:
+                raise ValueError("document does not contain any sections")
+            target_section = self._root.sections[-1]
+        return target_section.properties.set_header_text(text, page_type=page_type)
+
+    def set_footer_text(
+        self,
+        text: str,
+        *,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        page_type: str = "BOTH",
+    ) -> HwpxOxmlSectionHeaderFooter:
+        """Ensure the requested section contains a footer for *page_type* and set its text."""
+
+        target_section = section
+        if target_section is None and section_index is not None:
+            target_section = self._root.sections[section_index]
+        if target_section is None:
+            if not self._root.sections:
+                raise ValueError("document does not contain any sections")
+            target_section = self._root.sections[-1]
+        return target_section.properties.set_footer_text(text, page_type=page_type)
+
+    def remove_header(
+        self,
+        *,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        page_type: str = "BOTH",
+    ) -> None:
+        """Remove the header linked to *page_type* from the requested section if present."""
+
+        target_section = section
+        if target_section is None and section_index is not None:
+            target_section = self._root.sections[section_index]
+        if target_section is None:
+            if not self._root.sections:
+                return
+            target_section = self._root.sections[-1]
+        target_section.properties.remove_header(page_type=page_type)
+
+    def remove_footer(
+        self,
+        *,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+        page_type: str = "BOTH",
+    ) -> None:
+        """Remove the footer linked to *page_type* from the requested section if present."""
+
+        target_section = section
+        if target_section is None and section_index is not None:
+            target_section = self._root.sections[section_index]
+        if target_section is None:
+            if not self._root.sections:
+                return
+            target_section = self._root.sections[-1]
+        target_section.properties.remove_footer(page_type=page_type)
+
     def save(
         self,
         path_or_stream: str | PathLike[str] | BinaryIO | None = None,

{python-hwpx-1.2 → python-hwpx-1.3}/src/hwpx/oxml/__init__.py

@@ -39,6 +39,9 @@ from .document import (
 from .header import (
     BeginNum,
     BorderFillList,
+    Bullet,
+    BulletList,
+    BulletParaHead,
     CharProperty,
     CharPropertyList,
     DocOption,
@@ -56,16 +59,48 @@ from .header import (
     MemoProperties,
     MemoShape,
     NumberingList,
+    ParagraphAlignment,
+    ParagraphAutoSpacing,
+    ParagraphBreakSetting,
+    ParagraphBorder,
+    ParagraphHeading,
+    ParagraphLineSpacing,
+    ParagraphMargin,
+    ParagraphProperty,
+    ParagraphPropertyList,
     RefList,
+    Style,
+    StyleList,
     TabProperties,
+    TrackChange,
+    TrackChangeAuthor,
+    TrackChangeAuthorList,
     TrackChangeConfig,
+    TrackChangeList,
     memo_shape_from_attributes,
     parse_begin_num,
+    parse_bullet,
+    parse_bullet_para_head,
+    parse_bullets,
     parse_doc_option,
     parse_header_element,
     parse_memo_properties,
     parse_memo_shape,
+    parse_paragraph_alignment,
+    parse_paragraph_auto_spacing,
+    parse_paragraph_border,
+    parse_paragraph_break_setting,
+    parse_paragraph_line_spacing,
+    parse_paragraph_margin,
+    parse_paragraph_property,
+    parse_paragraph_properties,
     parse_ref_list,
+    parse_style,
+    parse_styles,
+    parse_track_change,
+    parse_track_change_author,
+    parse_track_change_authors,
+    parse_track_changes,
 )
 from .parser import element_to_model, parse_header_xml, parse_section_xml
 from .schema import load_schema
@@ -74,6 +109,9 @@ from .utils import XmlSource
 __all__ = [
     "BeginNum",
     "BorderFillList",
+    "Bullet",
+    "BulletList",
+    "BulletParaHead",
     "CharProperty",
     "CharPropertyList",
     "DocOption",
@@ -106,6 +144,15 @@ __all__ = [
     "MemoProperties",
     "MemoShape",
     "NumberingList",
+    "ParagraphAlignment",
+    "ParagraphAutoSpacing",
+    "ParagraphBreakSetting",
+    "ParagraphBorder",
+    "ParagraphHeading",
+    "ParagraphLineSpacing",
+    "ParagraphMargin",
+    "ParagraphProperty",
+    "ParagraphPropertyList",
     "Paragraph",
     "PageMargins",
     "PageSize",
@@ -115,22 +162,45 @@ __all__ = [
     "Run",
     "Section",
     "SectionStartNumbering",
+    "Style",
+    "StyleList",
     "TabProperties",
-    "TextSpan",
+    "TrackChange",
+    "TrackChangeAuthor",
+    "TrackChangeAuthorList",
     "TrackChangeConfig",
+    "TrackChangeList",
+    "TextSpan",
     "XmlSource",
     "element_to_model",
     "load_schema",
     "parse_begin_num",
+    "parse_bullet",
+    "parse_bullet_para_head",
+    "parse_bullets",
     "parse_doc_option",
     "parse_generic_element",
     "parse_header_element",
     "parse_memo_properties",
     "parse_memo_shape",
+    "parse_paragraph_alignment",
+    "parse_paragraph_auto_spacing",
+    "parse_paragraph_border",
+    "parse_paragraph_break_setting",
+    "parse_paragraph_line_spacing",
+    "parse_paragraph_margin",
+    "parse_paragraph_property",
+    "parse_paragraph_properties",
     "parse_header_xml",
     "parse_paragraph_element",
     "parse_ref_list",
     "parse_run_element",
+    "parse_style",
+    "parse_styles",
+    "parse_track_change",
+    "parse_track_change_author",
+    "parse_track_change_authors",
+    "parse_track_changes",
     "parse_section_element",
     "parse_section_xml",
     "parse_text_span",