python-hwpx 2.21.0__tar.gz → 2.23.0__tar.gz

python_hwpx-2.23.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: python-hwpx
+Version: 2.23.0
+Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
+Author: python-hwpx Maintainers
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/airmang/python-hwpx
+Project-URL: Documentation, https://airmang.github.io/python-hwpx/
+Project-URL: Issues, https://github.com/airmang/python-hwpx/issues
+Keywords: hwp,hwpx,hancom,opc,xml,document-automation,validation,template
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+License-File: NOTICE
+Requires-Dist: lxml<6,>=4.9
+Provides-Extra: visual
+Requires-Dist: pymupdf>=1.24; extra == "visual"
+Requires-Dist: pillow>=10.0; extra == "visual"
+Requires-Dist: numpy>=1.26; extra == "visual"
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+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: build>=1.0; extra == "test"
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: typecheck
+Requires-Dist: mypy>=1.10; extra == "typecheck"
+Requires-Dist: pyright>=1.1.390; extra == "typecheck"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">python-hwpx</h1>
+  <p align="center">
+    <strong>한글 없이 HWPX 문서를 Python으로 읽고, 편집하고, 생성하고, 검증합니다.</strong>
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
+    <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
+    <a href="https://airmang.github.io/python-hwpx/"><img src="https://img.shields.io/badge/docs-Sphinx-8CA1AF" alt="Docs"></a>
+  </p>
+</p>
+
+---
+
+## 🧩 HWPX Stack (3종)
+
+| 계층 | 레포 | 역할 |
+|---|---|---|
+| 📦 라이브러리 | **[`python-hwpx`](https://github.com/airmang/python-hwpx)** | 순수 파이썬 HWPX 파싱·편집·생성 코어 |
+| 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
+| 🎯 에이전트 스킬 | [`hwpx-skill`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 공식 온보딩 스킬 |
+
+---
+
+## 왜 python-hwpx인가
+
+- **한컴오피스 설치 불필요** — HWPX는 ZIP+XML(OWPML/OPC) 구조라, 순수 파이썬으로 Windows·macOS·Linux·CI 어디서나 읽고 씁니다.
+- **읽기부터 생성까지 한 코어** — 텍스트/서식 추출, 문단·표·양식 편집, 새 문서 생성, XSD 스키마 검증을 하나의 API로 처리합니다.
+- **에이전트·자동화 친화** — 같은 스택 위에서 `hwpx-mcp-server`와 공식 스킬이 직결됩니다.
+
+## 빠른 시작
+
+```bash
+pip install python-hwpx      # Python 3.10+ · lxml ≥ 4.9
+```
+
+```python
+from hwpx import HwpxDocument
+
+# 기존 문서 열기 → 편집 → 저장
+doc = HwpxDocument.open("보고서.hwpx")
+doc.add_paragraph("자동화로 추가한 문단입니다.")
+doc.save_to_path("보고서-수정.hwpx")
+
+# 새 문서 만들기
+new = HwpxDocument.new()
+new.add_paragraph("python-hwpx로 만든 새 문서")
+new.save_to_path("새문서.hwpx")
+```
+
+> 💡 컨텍스트 매니저도 지원합니다 — `with` 블록을 벗어나면 리소스가 자동 정리됩니다:
+> ```python
+> with HwpxDocument.open("보고서.hwpx") as doc:
+>     doc.add_paragraph("자동으로 리소스가 정리됩니다.")
+>     doc.save_to_path("결과물.hwpx")
+> ```
+
+`open`/`new` → `edit`/`extract` → `save_to_path` 흐름만 잡으면 나머지는 필요할 때 확장하면 됩니다.
+
+## 무엇을 하나
+
+### 🔍 읽기 · 추출
+- 텍스트/HTML/Markdown 내보내기 — `export_text()` · `export_html()` · `export_markdown()`
+- **풍부한 Markdown** — `export_rich_markdown()`은 인라인 서식(`**굵게**`·`*기울임*`·`~~취소선~~`), 중첩 표(colspan/rowspan 안전), 도형 텍스트, 이미지, 각주/미주, 하이퍼링크, 제목(`#`/`##`) 자동 감지까지 보존
+- `TextExtractor` / `ObjectFinder` — 섹션·문단 순회, 태그·속성·XPath로 객체 탐색 (`hp:tab`은 `\t`로 보존, roundtrip 안전)
+
+```python
+doc = HwpxDocument.open("보고서.hwpx")
+md = doc.export_rich_markdown(
+    image_dir="out/images",       # BinData 이미지를 디스크에 추출
+    image_ref_prefix="images/",   # 마크다운 내 ![](images/...) 경로 접두
+    detect_headings=True,         # Ⅰ./1. 패턴 기반 #/## 자동
+)
+```
+
+### ✏️ 편집
+- 문단 추가/삭제/서식, Run 단위 볼드·이탤릭·밑줄·색상
+- 섹션 추가/삭제(`add_section(after=)`·`remove_section()`, manifest 자동 관리)
+- 표 생성·셀 텍스트·병합/분할·중첩 테이블, 이미지 임베드, 머리글/바닥글, 메모(앵커 기반), 각주/미주, 북마크/하이퍼링크, 다단 편집
+- **기존 문서 서식 편집** — 정렬·줄간격·들여쓰기·문단 간격, 용지·여백·방향, 쪽번호, 불릿/번호
+- **스타일 기반 치환** — 색상·밑줄·`charPrIDRef`로 Run을 필터링해 선택 교체(`replace_text_in_runs`·`find_runs_by_style`)
+
+```python
+# 빨간색 텍스트만 찾아서 치환
+doc.replace_text_in_runs("임시", "확정", text_color="#FF0000")
+```
+
+### 🖊️ 양식 채우기 (byte-preserving)
+- 누름틀(클릭히어) 필드 조회·서식 보존 채움, 라벨 기반 셀 탐색(`find_cell_by_label`)·경로 채우기(`fill_by_path`)
+- **바이트 보존 구조 편집** — 셀 채우기 / 행·열·표 삭제·삽입 / 열 너비 오토핏 / 폰트 shrink-to-fit 을 문서 재조립 없이 수행해 양식 서식을 그대로 보존. 미수정 영역은 `hwpx.patch`가 section XML 바이트를 splice해 손대지 않음
+
+```python
+doc = HwpxDocument.open("신청서.hwpx")
+result = doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
+doc.save_to_path("신청서-작성완료.hwpx")
+print(result["applied_count"], result["failed_count"])
+```
+
+### 🏗️ 생성 · 공문서 도구
+- `hwpx.builder` — Section/Heading/Table/Image/Header 조립형 생성 + 하드게이트 저장 리포트
+- 공문서 도구 — `official_lint`(항목기호 위계·"끝." 표시·붙임·날짜 lint), 결재란 프리셋
+- `advanced_generators` — 사진대지(image_grid)·회의 명패·표 기반 조직도
+- `mail_merge` — 템플릿+데이터 N부 대량 생성, 표 합계·평균 계산
+- `doc_diff` — 문단 LCS diff·신구대조표·참조 정합 lint
+- `style_profile` — 참조 문서 프로파일 추출·적용, 템플릿 레지스트리
+
+### ✅ 검증 · 안전 · 저수준
+- XSD 스키마 + 패키지 구조 검증 — CLI `hwpx-validate` · `hwpx-validate-package`, `hwpx-analyze-template`
+- `validate_editor_open_safety` — 저장/팩/리페어/빌더 출력 게이트, `openSafety` 증거 반환
+- `hwpx.tools.fuzz`(시드 결정적 시나리오·3중 오라클) · `hwpx.tools.layout_preview`(페이지 박스 근사 HTML/PNG 자기검증) · `opc.security`(XML entity·ZIP 압축 폭탄 가드)
+- `hwpx.oxml` 데이터클래스로 OWPML 스키마 ↔ Python 객체 직접 조작, HWPML 2016→2011 네임스페이스 자동 정규화
+
+```bash
+hwpx-validate-package 보고서.hwpx
+hwpx-analyze-template 보고서.hwpx
+```
+
+> 전체 기능·클래스·메서드 목록은 [사용 가이드](docs/usage.md)와 [API 레퍼런스](https://airmang.github.io/python-hwpx/api_reference.html)를 참고하세요.
+
+## 대항 라이브러리 비교
+
+| | python-hwpx | pyhwpx | pyhwp |
+|---|---|---|---|
+| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
+| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
+| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
+| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
+| **스키마 검증** | ✅ | ❌ | ❌ |
+| **AI 에이전트 연동 (MCP)** | ✅ `hwpx-mcp-server` | ❌ | ❌ |
+
+> HWP(v5 바이너리) 파일은 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
+
+## 알려진 제약
+
+- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않습니다. 복잡한 개체 추가 시 한/글에서 열어 검증하세요.
+- 이미지 바이너리 임베드는 지원하지만 `<hp:pic>` 요소의 완전 자동 생성은 제공하지 않습니다.
+- 암호화된 HWPX 파일의 암복호화는 지원하지 않습니다.
+
+## 더 보기
+
+- **[🚀 빠른 시작](docs/quickstart.md)** · **[📚 사용 가이드](docs/usage.md)** — 첫 파일 열기부터 문단·표·메모·섹션 편집, 텍스트 추출·검증까지
+- **[💡 예제 모음](docs/examples.md)** · [`examples/`](examples/) — `build_release_checklist.py`(메모·스타일 편집 HWPX 생성), `extract_text.py`(CLI 텍스트 추출), `find_objects.py`(OWPML 노드 추적) 등
+- **[📐 스키마 개요](docs/schema-overview.md)** · **[🔧 설치 검증](docs/installation.md)**
+- **[📖 전체 문서 (Sphinx)](https://airmang.github.io/python-hwpx/)** — API 레퍼런스·50+ 실전 패턴·FAQ
+- **[📝 CHANGELOG](CHANGELOG.md)** · **[🤝 CONTRIBUTING](CONTRIBUTING.md)** · **[👥 CONTRIBUTORS](CONTRIBUTORS.md)**
+
+## 기여하기
+
+버그 리포트, 기능 제안, PR 모두 환영합니다.
+
+```bash
+git clone https://github.com/airmang/python-hwpx.git
+cd python-hwpx
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+Apache License 2.0. See LICENSE and NOTICE.
+
+## Maintainer
+
+Primary maintainer/contact: **고규현** — 광교고등학교 정보·컴퓨터 교사
+
+- ✉️ [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
+- 🐙 [@airmang](https://github.com/airmang)

python_hwpx-2.23.0/README.md

@@ -0,0 +1,171 @@
+<p align="center">
+  <h1 align="center">python-hwpx</h1>
+  <p align="center">
+    <strong>한글 없이 HWPX 문서를 Python으로 읽고, 편집하고, 생성하고, 검증합니다.</strong>
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
+    <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
+    <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
+    <a href="https://airmang.github.io/python-hwpx/"><img src="https://img.shields.io/badge/docs-Sphinx-8CA1AF" alt="Docs"></a>
+  </p>
+</p>
+
+---
+
+## 🧩 HWPX Stack (3종)
+
+| 계층 | 레포 | 역할 |
+|---|---|---|
+| 📦 라이브러리 | **[`python-hwpx`](https://github.com/airmang/python-hwpx)** | 순수 파이썬 HWPX 파싱·편집·생성 코어 |
+| 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
+| 🎯 에이전트 스킬 | [`hwpx-skill`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 공식 온보딩 스킬 |
+
+---
+
+## 왜 python-hwpx인가
+
+- **한컴오피스 설치 불필요** — HWPX는 ZIP+XML(OWPML/OPC) 구조라, 순수 파이썬으로 Windows·macOS·Linux·CI 어디서나 읽고 씁니다.
+- **읽기부터 생성까지 한 코어** — 텍스트/서식 추출, 문단·표·양식 편집, 새 문서 생성, XSD 스키마 검증을 하나의 API로 처리합니다.
+- **에이전트·자동화 친화** — 같은 스택 위에서 `hwpx-mcp-server`와 공식 스킬이 직결됩니다.
+
+## 빠른 시작
+
+```bash
+pip install python-hwpx      # Python 3.10+ · lxml ≥ 4.9
+```
+
+```python
+from hwpx import HwpxDocument
+
+# 기존 문서 열기 → 편집 → 저장
+doc = HwpxDocument.open("보고서.hwpx")
+doc.add_paragraph("자동화로 추가한 문단입니다.")
+doc.save_to_path("보고서-수정.hwpx")
+
+# 새 문서 만들기
+new = HwpxDocument.new()
+new.add_paragraph("python-hwpx로 만든 새 문서")
+new.save_to_path("새문서.hwpx")
+```
+
+> 💡 컨텍스트 매니저도 지원합니다 — `with` 블록을 벗어나면 리소스가 자동 정리됩니다:
+> ```python
+> with HwpxDocument.open("보고서.hwpx") as doc:
+>     doc.add_paragraph("자동으로 리소스가 정리됩니다.")
+>     doc.save_to_path("결과물.hwpx")
+> ```
+
+`open`/`new` → `edit`/`extract` → `save_to_path` 흐름만 잡으면 나머지는 필요할 때 확장하면 됩니다.
+
+## 무엇을 하나
+
+### 🔍 읽기 · 추출
+- 텍스트/HTML/Markdown 내보내기 — `export_text()` · `export_html()` · `export_markdown()`
+- **풍부한 Markdown** — `export_rich_markdown()`은 인라인 서식(`**굵게**`·`*기울임*`·`~~취소선~~`), 중첩 표(colspan/rowspan 안전), 도형 텍스트, 이미지, 각주/미주, 하이퍼링크, 제목(`#`/`##`) 자동 감지까지 보존
+- `TextExtractor` / `ObjectFinder` — 섹션·문단 순회, 태그·속성·XPath로 객체 탐색 (`hp:tab`은 `\t`로 보존, roundtrip 안전)
+
+```python
+doc = HwpxDocument.open("보고서.hwpx")
+md = doc.export_rich_markdown(
+    image_dir="out/images",       # BinData 이미지를 디스크에 추출
+    image_ref_prefix="images/",   # 마크다운 내 ![](images/...) 경로 접두
+    detect_headings=True,         # Ⅰ./1. 패턴 기반 #/## 자동
+)
+```
+
+### ✏️ 편집
+- 문단 추가/삭제/서식, Run 단위 볼드·이탤릭·밑줄·색상
+- 섹션 추가/삭제(`add_section(after=)`·`remove_section()`, manifest 자동 관리)
+- 표 생성·셀 텍스트·병합/분할·중첩 테이블, 이미지 임베드, 머리글/바닥글, 메모(앵커 기반), 각주/미주, 북마크/하이퍼링크, 다단 편집
+- **기존 문서 서식 편집** — 정렬·줄간격·들여쓰기·문단 간격, 용지·여백·방향, 쪽번호, 불릿/번호
+- **스타일 기반 치환** — 색상·밑줄·`charPrIDRef`로 Run을 필터링해 선택 교체(`replace_text_in_runs`·`find_runs_by_style`)
+
+```python
+# 빨간색 텍스트만 찾아서 치환
+doc.replace_text_in_runs("임시", "확정", text_color="#FF0000")
+```
+
+### 🖊️ 양식 채우기 (byte-preserving)
+- 누름틀(클릭히어) 필드 조회·서식 보존 채움, 라벨 기반 셀 탐색(`find_cell_by_label`)·경로 채우기(`fill_by_path`)
+- **바이트 보존 구조 편집** — 셀 채우기 / 행·열·표 삭제·삽입 / 열 너비 오토핏 / 폰트 shrink-to-fit 을 문서 재조립 없이 수행해 양식 서식을 그대로 보존. 미수정 영역은 `hwpx.patch`가 section XML 바이트를 splice해 손대지 않음
+
+```python
+doc = HwpxDocument.open("신청서.hwpx")
+result = doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
+doc.save_to_path("신청서-작성완료.hwpx")
+print(result["applied_count"], result["failed_count"])
+```
+
+### 🏗️ 생성 · 공문서 도구
+- `hwpx.builder` — Section/Heading/Table/Image/Header 조립형 생성 + 하드게이트 저장 리포트
+- 공문서 도구 — `official_lint`(항목기호 위계·"끝." 표시·붙임·날짜 lint), 결재란 프리셋
+- `advanced_generators` — 사진대지(image_grid)·회의 명패·표 기반 조직도
+- `mail_merge` — 템플릿+데이터 N부 대량 생성, 표 합계·평균 계산
+- `doc_diff` — 문단 LCS diff·신구대조표·참조 정합 lint
+- `style_profile` — 참조 문서 프로파일 추출·적용, 템플릿 레지스트리
+
+### ✅ 검증 · 안전 · 저수준
+- XSD 스키마 + 패키지 구조 검증 — CLI `hwpx-validate` · `hwpx-validate-package`, `hwpx-analyze-template`
+- `validate_editor_open_safety` — 저장/팩/리페어/빌더 출력 게이트, `openSafety` 증거 반환
+- `hwpx.tools.fuzz`(시드 결정적 시나리오·3중 오라클) · `hwpx.tools.layout_preview`(페이지 박스 근사 HTML/PNG 자기검증) · `opc.security`(XML entity·ZIP 압축 폭탄 가드)
+- `hwpx.oxml` 데이터클래스로 OWPML 스키마 ↔ Python 객체 직접 조작, HWPML 2016→2011 네임스페이스 자동 정규화
+
+```bash
+hwpx-validate-package 보고서.hwpx
+hwpx-analyze-template 보고서.hwpx
+```
+
+> 전체 기능·클래스·메서드 목록은 [사용 가이드](docs/usage.md)와 [API 레퍼런스](https://airmang.github.io/python-hwpx/api_reference.html)를 참고하세요.
+
+## 대항 라이브러리 비교
+
+| | python-hwpx | pyhwpx | pyhwp |
+|---|---|---|---|
+| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
+| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
+| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
+| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
+| **스키마 검증** | ✅ | ❌ | ❌ |
+| **AI 에이전트 연동 (MCP)** | ✅ `hwpx-mcp-server` | ❌ | ❌ |
+
+> HWP(v5 바이너리) 파일은 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
+
+## 알려진 제약
+
+- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않습니다. 복잡한 개체 추가 시 한/글에서 열어 검증하세요.
+- 이미지 바이너리 임베드는 지원하지만 `<hp:pic>` 요소의 완전 자동 생성은 제공하지 않습니다.
+- 암호화된 HWPX 파일의 암복호화는 지원하지 않습니다.
+
+## 더 보기
+
+- **[🚀 빠른 시작](docs/quickstart.md)** · **[📚 사용 가이드](docs/usage.md)** — 첫 파일 열기부터 문단·표·메모·섹션 편집, 텍스트 추출·검증까지
+- **[💡 예제 모음](docs/examples.md)** · [`examples/`](examples/) — `build_release_checklist.py`(메모·스타일 편집 HWPX 생성), `extract_text.py`(CLI 텍스트 추출), `find_objects.py`(OWPML 노드 추적) 등
+- **[📐 스키마 개요](docs/schema-overview.md)** · **[🔧 설치 검증](docs/installation.md)**
+- **[📖 전체 문서 (Sphinx)](https://airmang.github.io/python-hwpx/)** — API 레퍼런스·50+ 실전 패턴·FAQ
+- **[📝 CHANGELOG](CHANGELOG.md)** · **[🤝 CONTRIBUTING](CONTRIBUTING.md)** · **[👥 CONTRIBUTORS](CONTRIBUTORS.md)**
+
+## 기여하기
+
+버그 리포트, 기능 제안, PR 모두 환영합니다.
+
+```bash
+git clone https://github.com/airmang/python-hwpx.git
+cd python-hwpx
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+Apache License 2.0. See LICENSE and NOTICE.
+
+## Maintainer
+
+Primary maintainer/contact: **고규현** — 광교고등학교 정보·컴퓨터 교사
+
+- ✉️ [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)
+- 🐙 [@airmang](https://github.com/airmang)

{python_hwpx-2.21.0 → python_hwpx-2.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.21.0"
+version = "2.23.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-2.21.0 → python_hwpx-2.23.0}/src/hwpx/table_patch.py

@@ -196,6 +196,80 @@ def _all_paragraph_spans(cell: bytes) -> list[tuple[int, int]]:
     return [(m.start(), m.end()) for m in _P_SPAN_RE.finditer(masked)]
 
 
+# --- font shrink-to-fit helpers (byte-preserving charPr materialisation) ------
+
+def _header_part_name(parts: Mapping[str, bytes]) -> str | None:
+    return next((n for n in parts if n.endswith("header.xml")), None)
+
+def _charpr_height(header: bytes, cid: str) -> int | None:
+    m = re.search(rb'<(?:[A-Za-z_][\w.-]*:)?charPr\b[^>]*?\bid="' + re.escape(cid.encode()) + rb'"[^>]*?\bheight="(\d+)"', header)
+    return int(m.group(1)) if m else None
+
+def _cell_run_charpr(cell: bytes) -> str | None:
+    m = re.search(rb'<(?:[A-Za-z_][\w.-]*:)?run\b[^>]*?\bcharPrIDRef="(\d+)"', cell)
+    return m.group(1).decode() if m else None
+
+def _cell_inner_width(cell: bytes) -> int:
+    w = _iattr(cell, "cellSz", "width") or 0
+    m = re.search(rb'<(?:[A-Za-z_][\w.-]*:)?cellMargin\b[^>]*?\bleft="(\d+)"[^>]*?\bright="(\d+)"', cell)
+    left, right = (int(m.group(1)), int(m.group(2))) if m else (0, 0)
+    return max(w - left - right, 0)
+
+def _materialize_charpr(header: bytes, base_id: str, new_height: int, cache: dict[tuple[str, int], str]) -> tuple[bytes, str]:
+    """Clone charPr *base_id* with *new_height*, append it to the charProperties
+    list (itemCnt bumped), return (new_header, new_charpr_id). Deduped via *cache*."""
+    key = (base_id, new_height)
+    if key in cache:
+        return header, cache[key]
+    bid = re.escape(base_id.encode())
+    m = re.search(rb'<(?:[A-Za-z_][\w.-]*:)?charPr\b[^>]*?\bid="' + bid + rb'".*?</(?:[A-Za-z_][\w.-]*:)?charPr>', header, re.DOTALL)
+    if m is None:
+        m = re.search(rb'<(?:[A-Za-z_][\w.-]*:)?charPr\b[^>]*?\bid="' + bid + rb'"[^>]*/>', header)
+    if m is None:
+        raise KeyError(f"base charPr {base_id} not found")
+    ids = [int(x) for x in re.findall(rb'<(?:[A-Za-z_][\w.-]*:)?charPr\b[^>]*?\bid="(\d+)"', header)]
+    new_id = str((max(ids) + 1) if ids else 0)
+    clone = re.sub(rb'(\bid=")\d+(")', rb'\g<1>' + new_id.encode() + rb'\g<2>', m.group(0), count=1)
+    if re.search(rb'\bheight="\d+"', clone):
+        clone = re.sub(rb'(\bheight=")\d+(")', rb'\g<1>' + str(new_height).encode() + rb'\g<2>', clone, count=1)
+    close = re.search(rb'</(?:[A-Za-z_][\w.-]*:)?charProperties>', header)
+    if close is None:
+        raise KeyError("charProperties close tag not found")
+    header = header[:close.start()] + clone + header[close.start():]
+    header = re.sub(
+        rb'(<(?:[A-Za-z_][\w.-]*:)?charProperties\b[^>]*?\bitemCnt=")(\d+)(")',
+        lambda mm: mm.group(1) + str(int(mm.group(2)) + 1).encode() + mm.group(3),
+        header, count=1,
+    )
+    cache[key] = new_id
+    return header, new_id
+
+def _shrunk_font_id(header: bytes, cell_bytes: bytes, text: str, target_lines: int, min_font_pt: float,
+                    cache: dict[tuple[str, int], str]) -> tuple[bytes, str, str] | None:
+    """If *text* needs more than *target_lines* at the cell's base font, decide a
+    shrink (form_fit FitEngine) and materialise it. Returns (new_header, base_id,
+    new_id) or None (no shrink needed / not resolvable)."""
+    from .form_fit.engine import FitEngine
+    from .form_fit.measure import SlotMetrics
+    from .form_fit.policy import FitPolicy
+
+    base_id = _cell_run_charpr(cell_bytes)
+    if base_id is None:
+        return None
+    inner = _cell_inner_width(cell_bytes)
+    base_h = _charpr_height(header, base_id)
+    if not inner or not base_h:
+        return None
+    base_pt = base_h / 100.0
+    slot = SlotMetrics(available_width=inner * 0.94, font_pt=base_pt, max_lines=target_lines)
+    result = FitEngine().fit(text, slot, FitPolicy(mode="wrap_then_shrink", max_lines=target_lines, min_font_pt=min_font_pt))
+    new_pt = result.font_pt
+    if not new_pt or new_pt >= base_pt - 1e-6:
+        return None
+    header, new_id = _materialize_charpr(header, base_id, int(round(new_pt * 100)), cache)
+    return header, base_id, new_id
+
+
 # --- public API ---------------------------------------------------------------
 
 @dataclass(frozen=True)
@@ -256,16 +330,17 @@ class CellFillResult:
         }
 
 
-def _normalize(cell: Mapping[str, Any] | Any) -> tuple[str, int, int, int, str]:
+def _normalize(cell: Mapping[str, Any] | Any) -> tuple[str, int, int, int, str, int | None]:
     get = cell.get if isinstance(cell, Mapping) else (lambda k, d=None: getattr(cell, k, d))
     section = str(get("section_path") or get("sectionPath") or "Contents/section0.xml")
     table_index = get("table_index", get("tableIndex"))
     row = get("row")
     col = get("col")
     text = get("text")
+    max_lines = get("max_lines", get("maxLines"))
     if table_index is None or row is None or col is None or text is None:
         raise ValueError("cell fill requires table_index, row, col, text")
-    return section, int(table_index), int(row), int(col), str(text)
+    return section, int(table_index), int(row), int(col), str(text), (int(max_lines) if max_lines else None)
 
 
 def fill_cells(
@@ -273,6 +348,8 @@ def fill_cells(
     cells: Sequence[Mapping[str, Any] | Any],
     *,
     output_path: str | Path | None = None,
+    fit_max_lines: int | None = None,
+    min_font_pt: float = 8.0,
 ) -> CellFillResult:
     """Byte-preserving fill of table cells by ``(table_index, row, col)`` address.
 
@@ -281,6 +358,12 @@ def fill_cells(
     parts and untouched tables round-trip byte-identical. Empty / self-closing
     cells are filled (text inserted), never silently reported as done. An
     unresolvable address is reported in ``skipped`` and mutates nothing.
+
+    **Font shrink-to-fit** (optional): when ``fit_max_lines`` is set (or a cell
+    carries ``max_lines``), a cell whose text would wrap past that many lines at
+    its template font is shrunk — the smallest font ``>= min_font_pt`` that fits
+    (form_fit FitEngine) is materialised as a real ``charPr`` and the cell's run
+    points at it. Column widths and the rest of the document are untouched.
     """
     source_bytes = _read_source_bytes(source)
     specs = [_normalize(c) for c in cells]
@@ -292,23 +375,28 @@ def fill_cells(
     with zipfile.ZipFile(io.BytesIO(source_bytes), "r") as zf:
         parts = {i.filename: zf.read(i.filename) for i in zf.infolist() if not i.is_dir()}
 
+    header_name = _header_part_name(parts)
+    header_xml = parts.get(header_name) if header_name else None
+    charpr_cache: dict[tuple[str, int], str] = {}
+    header_changed = False
+
     applied: list[CellApplied] = []
     skipped: list[CellSkipped] = []
-    by_section: dict[str, list[tuple[int, int, int, str]]] = {}
-    for section, ti, row, col, text in specs:
-        by_section.setdefault(section, []).append((ti, row, col, text))
+    by_section: dict[str, list[tuple[int, int, int, str, int | None]]] = {}
+    for section, ti, row, col, text, mx in specs:
+        by_section.setdefault(section, []).append((ti, row, col, text, mx))
 
     changed_parts: dict[str, bytes] = {}
     for section_path, section_specs in by_section.items():
         section_xml = parts.get(section_path)
         if section_xml is None:
-            skipped.extend(CellSkipped(section_path, ti, r, c, "section part not found") for ti, r, c, _ in section_specs)
+            skipped.extend(CellSkipped(section_path, ti, r, c, "section part not found") for ti, r, c, _t, _m in section_specs)
             continue
         table_spans = _iter_table_spans(section_xml)
         # accumulate byte edits over the whole section (table region splices)
         section_edits: list[tuple[int, int, bytes]] = []
         occupied: list[tuple[int, int]] = []  # filled paragraph spans (merge-collision guard)
-        for ti, row, col, text in section_specs:
+        for ti, row, col, text, mx in section_specs:
             if ti < 0 or ti >= len(table_spans):
                 skipped.append(CellSkipped(section_path, ti, row, col, "table_index out of range"))
                 continue
@@ -324,6 +412,16 @@ def fill_cells(
             if not p_spans:
                 skipped.append(CellSkipped(section_path, ti, row, col, "cell has no paragraph"))
                 continue
+            # Font shrink-to-fit: a cell with a max-lines target whose text would
+            # wrap past it gets its run pointed at a smaller (materialised) charPr.
+            shrink: tuple[str, str] | None = None
+            target = mx or fit_max_lines
+            if target and header_xml is not None and text.strip():
+                res = _shrunk_font_id(header_xml, cell_bytes, text, target, min_font_pt, charpr_cache)
+                if res is not None:
+                    header_xml, base_id, new_id = res
+                    header_changed = True
+                    shrink = (base_id, new_id)
             # Replace the WHOLE cell's visible text with `text`: line k -> paragraph k,
             # trailing paragraphs are emptied (so stale multi-line template content —
             # e.g. stacked 성취기준 codes — does not survive). newline-separated text
@@ -348,6 +446,9 @@ def fill_cells(
                     collided = True
                     break
                 new_para = _strip_paragraph_layout_cache(replacement if (_s, _e) == (0, len(para)) else _apply_edits(para, [(_s, _e, replacement)]))
+                if shrink is not None:
+                    base_id, new_id = shrink
+                    new_para = re.sub(rb'(charPrIDRef=")' + re.escape(base_id.encode()) + rb'(")', rb"\g<1>" + new_id.encode() + rb"\g<2>", new_para)
                 occupied.append((a0, a1))
                 cell_edits.append((a0, a1, new_para))
             if collided:
@@ -362,6 +463,9 @@ def fill_cells(
             if new_section != section_xml:
                 changed_parts[section_path] = new_section
 
+    if header_changed and header_name and header_xml is not None:
+        changed_parts[header_name] = header_xml
+
     if not changed_parts:
         open_safety, _ = _finalize(source_bytes, output_path, source=source)
         return CellFillResult(source_bytes, tuple(applied), tuple(skipped), (), True, "none", open_safety)
@@ -600,6 +704,57 @@ def _insert_row_by_clone(table: str, ref_row: int, count: int = 1) -> str:
     return _rebuild(prefix, new_rows, suffix, rowcnt=len(new_rows))
 
 
+def _set_column_widths(table: str, new_widths: dict[int, int]) -> str:
+    """Set logical column widths (HWPUNIT). Each cell's cellSz.width = sum of its
+    spanned columns' new widths. Byte-preserving cellSz edits; grid unchanged."""
+    _guard_flat(table)
+    prefix, rows, suffix = _parse_table(table)
+
+    def fix(tc: str):
+        ca = _si(tc, "cellAddr", "colAddr")
+        cs = _si(tc, "cellSpan", "colSpan") or 1
+        w = sum(int(new_widths.get(c, 0)) for c in range(ca, ca + cs))
+        if w > 0:
+            tc = _ss(tc, "cellSz", "width", w)
+        return tc
+
+    rows = [_map_cells(r, fix) for r in rows]
+    return _rebuild(prefix, rows, suffix)
+
+
+def _autofit_columns(table: str, *, min_frac: float = 0.06, damp: float = 0.5) -> str:
+    """Rebalance column widths to content: content-heavy columns widen, light ones
+    narrow, table total width preserved. Demand = longest single-span cell's text
+    width (form_fit advance model), sqrt-damped so a paragraph column doesn't run
+    away; every column keeps a floor of *min_frac* of the total."""
+    from .form_fit.measure import estimate_text_width
+
+    prefix, rows, suffix = _parse_table(table)
+    cur = _uniform_col_widths(rows)
+    if cur is None:
+        raise TableStructureError("no uniform (all colSpan=1) row to autofit widths")
+    ncol = max(cur) + 1
+    total = sum(cur.values())
+    demand = {c: 0.0 for c in range(ncol)}
+    for r in rows:
+        for tc in _S_TC.findall(r):
+            if (_si(tc, "cellSpan", "colSpan") or 1) != 1:
+                continue
+            ca = _si(tc, "cellAddr", "colAddr")
+            txt = "".join(re.findall(r"<hp:t>(.*?)</hp:t>", tc, re.DOTALL))
+            demand[ca] = max(demand[ca], estimate_text_width(txt, 10.0))
+    weight = {c: max(demand[c], 1.0) ** damp for c in range(ncol)}
+    sw = sum(weight.values()) or 1.0
+    floor = total * min_frac
+    raw = {c: max(floor, total * weight[c] / sw) for c in range(ncol)}
+    scale = total / (sum(raw.values()) or 1.0)
+    new = {c: int(round(raw[c] * scale)) for c in range(ncol)}
+    # absorb rounding drift into the widest column so the total is exact
+    drift = total - sum(new.values())
+    new[max(new, key=lambda c: new[c])] += drift
+    return _set_column_widths(table, new)
+
+
 def _validate_or_raise(table: str) -> None:
     _grid, rep = build_grid(table.encode("utf-8"))
     if not rep.ok:
@@ -608,10 +763,17 @@ def _validate_or_raise(table: str) -> None:
 
 # --- section-level application (byte-region splice back) ----------------------
 
+def _widths_arg(o: Mapping[str, Any]) -> dict[int, int]:
+    w = o["widths"]
+    return {int(k): int(v) for k, v in w.items()} if isinstance(w, Mapping) else {i: int(v) for i, v in enumerate(w)}
+
+
 _STRUCT_OPS = {
     "delete_column": lambda t, o: _collapse_empty_rows(_delete_columns(t, o["cols"] if "cols" in o else [o["col"]])),
     "delete_row": lambda t, o: _delete_rows(t, o["rows"] if "rows" in o else [o["row"]]),
     "insert_row_by_clone": lambda t, o: _insert_row_by_clone(t, o["ref_row"], int(o.get("count", 1))),
+    "set_column_widths": lambda t, o: _set_column_widths(t, _widths_arg(o)),
+    "autofit_columns": lambda t, o: _autofit_columns(t, min_frac=float(o.get("min_frac", 0.06)), damp=float(o.get("damp", 0.5))),
 }