python-hwpx 4.2.0__tar.gz → 5.0.2__tar.gz

python_hwpx-5.0.2/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: python-hwpx
+Version: 5.0.2
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: lxml<7,>=4.9
+Provides-Extra: visual
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+Provides-Extra: preview
+Requires-Dist: latex2mathml>=3.77; extra == "preview"
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: latex2mathml>=3.77; extra == "dev"
+Provides-Extra: test
+Requires-Dist: build>=1.0; extra == "test"
+Requires-Dist: numpy>=1.26; extra == "test"
+Requires-Dist: openpyxl>=3.1; extra == "test"
+Requires-Dist: pillow>=10.0; extra == "test"
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: pyyaml<7,>=6.0; extra == "test"
+Requires-Dist: ruff>=0.12; extra == "test"
+Requires-Dist: latex2mathml>=3.77; 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를 읽고, 고치고, 만드는 순수 파이썬 라이브러리</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://pepy.tech/project/python-hwpx"><img src="https://static.pepy.tech/badge/python-hwpx/month" alt="Downloads"></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/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></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>
+  </p>
+</p>
+
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
+읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
+곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
+형태로 만들어집니다.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
+</p>
+<p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
+
+**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
+
+```text
+이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
+(pip install python-hwpx 로 설치하면 돼)
+양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
+```
+
+설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
+
+| | 저장소 | 역할 |
+|---|---|---|
+| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
+| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | 저작·양식 채움 워크플로, `hwpx` CLI, 선택형 MCP 서버 |
+| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
+
+## 시작하기
+
+```bash
+pip install python-hwpx      # Python 3.10+
+```
+
+```python
+from hwpx import HwpxDocument
+
+doc = HwpxDocument.open("보고서.hwpx")
+doc.add_paragraph("자동화로 추가한 문단입니다.")
+doc.save_to_path("보고서-수정.hwpx")
+```
+
+백지에서 시작할 때는 `HwpxDocument.new()`로 만들어 같은 API로 문단·표·머리말을
+채우면 됩니다. 문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
+[`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)을
+함께 설치하세요.
+
+> 기존 설치 명령 호환을 위해 `pip install "python-hwpx[visual]"`도 계속
+> 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 —
+> 그 역할은 `python-hwpx-automation[oracle]`이 맡습니다.
+
+## 무엇을 하나
+
+- **읽기·추출** — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
+- **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
+- **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
+
+자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
+
+### 양식 채우기 — 서식은 그대로, 값만
+
+```python
+doc = HwpxDocument.open("신청서.hwpx")
+result = doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
+doc.save_to_path("신청서-작성완료.hwpx")
+```
+
+라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
+
+### 저장에는 영수증이 따라옵니다
+
+```python
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)        # "patch" — 문서 재조립 없이 저장됨
+print(report.preservation.untouched_part_payloads.to_dict())
+                                 # {"verified": 17, "changed": 0}
+```
+
+요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
+전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
+
+*예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
+쓰는 조각입니다. 예제별 Python 블록 판정은
+[실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
+
+## 실측으로 말합니다
+
+만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
+그대로 공개합니다:
+
+- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
+- **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
+- 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/hancom-open-generated.png" width="760" alt="ChatGPT 실행 환경에서 python-hwpx로 생성한 HWPX 문서를 실제 한컴오피스에서 연 모습">
+</p>
+<p align="center"><sub>ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.</sub></p>
+
+현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+
+> 위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는
+> 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
+
+## 어디서 쓰나
+
+| 환경 | 무엇을 하면 되나 |
+|---|---|
+| 일반 ChatGPT 대화 | `.hwpx`를 올리고 `pip install python-hwpx` 후 파이썬으로 편집해 되받기 |
+| 로컬·서버 파이썬 | `pip install python-hwpx` — 스크립트·배치·CI |
+| 파이썬 자동화 (MCP 없이) | `pip install python-hwpx-automation` — 저작·양식 채움·검증 워크플로를 그냥 파이썬으로 |
+| ChatGPT MCP 앱 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)의 MCP adapter를 커넥터로 등록 |
+| Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
+| Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
+
+실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
+편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
+플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
+오프라인 설치로 같은 여정이 됩니다.
+
+## 비교
+
+| | python-hwpx | pyhwpx | pyhwp |
+|---|---|---|---|
+| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
+| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
+| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
+| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
+| **AI 에이전트 연동 (MCP)** | ✅ companion 경유 | ❌ | ❌ |
+
+> HWP(v5 바이너리)는 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
+
+## 알려진 제약
+
+- `add_shape()` / `add_control()`은 저수준 탈출구라, 그대로 저장하면 한/글이
+  열지 못하는 파일이 됩니다(호출 시 경고만 나옵니다). 도형은 `add_line()` /
+  `add_rectangle()` / `add_ellipse()`를 쓰세요.
+- 그림은 단순 개체 생성까지 지원합니다 (그룹·효과 미지원).
+- 암호화된 HWPX는 지원하지 않습니다.
+
+## 기여하기
+
+[help wanted](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) ·
+[로드맵](https://github.com/airmang/python-hwpx/milestones) ·
+[Discussions](https://github.com/airmang/python-hwpx/discussions) ·
+[CONTRIBUTING](CONTRIBUTING.md)
+
+HWPX 내부 구조가 처음이라면 [내부 실전 가이드](docs/internals/)부터 — 실제 한/글
+동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
+공개 API의 안정 범위는 [안정 API 표면](docs/stable-api.md), 계층 간 소유권은
+[제품 경계 문서](docs/architecture/product-boundary.md)에 있습니다.
+
+## 감사의 말
+
+아래 공개 표준·프로젝트에 빚지고 있습니다.
+
+- **[OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX가 기반하는 한국 산업 표준
+- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 요소 구조 참조 모델 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 오라클 샘플 코퍼스
+- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 멱등성·검증 게이트 설계 영감
+- **범정부오피스** — 공무 문서 편집 워크플로 아이디어
+
+## License · Maintainer
+
+Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)

python_hwpx-5.0.2/README.md

@@ -0,0 +1,187 @@
+<p align="center">
+  <h1 align="center">python-hwpx</h1>
+  <p align="center">
+    <strong>한컴 없이 HWPX를 읽고, 고치고, 만드는 순수 파이썬 라이브러리</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://pepy.tech/project/python-hwpx"><img src="https://static.pepy.tech/badge/python-hwpx/month" alt="Downloads"></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/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></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>
+  </p>
+</p>
+
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
+읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
+곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
+형태로 만들어집니다.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
+</p>
+<p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
+
+**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
+
+```text
+이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
+(pip install python-hwpx 로 설치하면 돼)
+양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
+```
+
+설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
+
+| | 저장소 | 역할 |
+|---|---|---|
+| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
+| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | 저작·양식 채움 워크플로, `hwpx` CLI, 선택형 MCP 서버 |
+| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
+
+## 시작하기
+
+```bash
+pip install python-hwpx      # Python 3.10+
+```
+
+```python
+from hwpx import HwpxDocument
+
+doc = HwpxDocument.open("보고서.hwpx")
+doc.add_paragraph("자동화로 추가한 문단입니다.")
+doc.save_to_path("보고서-수정.hwpx")
+```
+
+백지에서 시작할 때는 `HwpxDocument.new()`로 만들어 같은 API로 문단·표·머리말을
+채우면 됩니다. 문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
+[`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)을
+함께 설치하세요.
+
+> 기존 설치 명령 호환을 위해 `pip install "python-hwpx[visual]"`도 계속
+> 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 —
+> 그 역할은 `python-hwpx-automation[oracle]`이 맡습니다.
+
+## 무엇을 하나
+
+- **읽기·추출** — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
+- **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
+- **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
+
+자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
+
+### 양식 채우기 — 서식은 그대로, 값만
+
+```python
+doc = HwpxDocument.open("신청서.hwpx")
+result = doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
+doc.save_to_path("신청서-작성완료.hwpx")
+```
+
+라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
+
+### 저장에는 영수증이 따라옵니다
+
+```python
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)        # "patch" — 문서 재조립 없이 저장됨
+print(report.preservation.untouched_part_payloads.to_dict())
+                                 # {"verified": 17, "changed": 0}
+```
+
+요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
+전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
+
+*예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
+쓰는 조각입니다. 예제별 Python 블록 판정은
+[실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
+
+## 실측으로 말합니다
+
+만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
+그대로 공개합니다:
+
+- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
+- **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
+- 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/hancom-open-generated.png" width="760" alt="ChatGPT 실행 환경에서 python-hwpx로 생성한 HWPX 문서를 실제 한컴오피스에서 연 모습">
+</p>
+<p align="center"><sub>ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.</sub></p>
+
+현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+
+> 위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는
+> 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
+
+## 어디서 쓰나
+
+| 환경 | 무엇을 하면 되나 |
+|---|---|
+| 일반 ChatGPT 대화 | `.hwpx`를 올리고 `pip install python-hwpx` 후 파이썬으로 편집해 되받기 |
+| 로컬·서버 파이썬 | `pip install python-hwpx` — 스크립트·배치·CI |
+| 파이썬 자동화 (MCP 없이) | `pip install python-hwpx-automation` — 저작·양식 채움·검증 워크플로를 그냥 파이썬으로 |
+| ChatGPT MCP 앱 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)의 MCP adapter를 커넥터로 등록 |
+| Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
+| Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
+
+실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
+편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
+플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
+오프라인 설치로 같은 여정이 됩니다.
+
+## 비교
+
+| | python-hwpx | pyhwpx | pyhwp |
+|---|---|---|---|
+| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
+| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
+| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
+| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
+| **AI 에이전트 연동 (MCP)** | ✅ companion 경유 | ❌ | ❌ |
+
+> HWP(v5 바이너리)는 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
+
+## 알려진 제약
+
+- `add_shape()` / `add_control()`은 저수준 탈출구라, 그대로 저장하면 한/글이
+  열지 못하는 파일이 됩니다(호출 시 경고만 나옵니다). 도형은 `add_line()` /
+  `add_rectangle()` / `add_ellipse()`를 쓰세요.
+- 그림은 단순 개체 생성까지 지원합니다 (그룹·효과 미지원).
+- 암호화된 HWPX는 지원하지 않습니다.
+
+## 기여하기
+
+[help wanted](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) ·
+[로드맵](https://github.com/airmang/python-hwpx/milestones) ·
+[Discussions](https://github.com/airmang/python-hwpx/discussions) ·
+[CONTRIBUTING](CONTRIBUTING.md)
+
+HWPX 내부 구조가 처음이라면 [내부 실전 가이드](docs/internals/)부터 — 실제 한/글
+동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
+공개 API의 안정 범위는 [안정 API 표면](docs/stable-api.md), 계층 간 소유권은
+[제품 경계 문서](docs/architecture/product-boundary.md)에 있습니다.
+
+## 감사의 말
+
+아래 공개 표준·프로젝트에 빚지고 있습니다.
+
+- **[OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX가 기반하는 한국 산업 표준
+- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 요소 구조 참조 모델 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 오라클 샘플 코퍼스
+- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 멱등성·검증 게이트 설계 영감
+- **범정부오피스** — 공무 문서 편집 워크플로 아이디어
+
+## License · Maintainer
+
+Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)

{python_hwpx-4.2.0 → python_hwpx-5.0.2}/pyproject.toml

@@ -1,11 +1,11 @@
 [build-system]
-requires = ["setuptools>=77.0.0", "wheel"]
+requires = ["setuptools==83.0.0", "wheel==0.47.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "4.2.0"
-description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
+version = "5.0.2"
+description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
@@ -21,19 +21,21 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries",
     "Topic :: Text Processing :: Markup :: XML",
+    "Typing :: Typed",
 ]
 dependencies = [
     "lxml>=4.9,<7",
 ]
 
 [project.optional-dependencies]
-visual = [
-    "pymupdf>=1.24",
-    "pillow>=10.0",
-    "numpy>=1.26",
-]
+# 5.0에서 core는 PDF도 이미지도 읽지 않는다. 렌더 백엔드와 word-box 추출은
+# 주입받는 계약이고, 그 스택은 companion 계층이 소유한다. 이름은 기존 설치가
+# `python-hwpx[visual]`로 깨지지 않도록 남기되 아무것도 끌어오지 않는다.
+visual = []
 # Excel(.xlsx/.xlsm) 명부 ingestion for mail_merge. Lazy-imported; absent => clear error.
 xlsx = [
     "openpyxl>=3.1",
@@ -52,9 +54,11 @@ dev = [
 test = [
     "build>=1.0",
     "numpy>=1.26",
+    "openpyxl>=3.1",
     "pillow>=10.0",
     "pytest>=7.4",
     "pytest-cov>=5.0",
+    "pyyaml>=6.0,<7",
     "ruff>=0.12",
     "latex2mathml>=3.77",
 ]
@@ -69,7 +73,11 @@ Documentation = "https://airmang.github.io/python-hwpx/"
 Issues = "https://github.com/airmang/python-hwpx/issues"
 
 [project.scripts]
-hwpx = "hwpx.agent.cli:main"
+# The `hwpx` application CLI moved to python-hwpx-automation, which declares the
+# name in the train that raises its core floor to 5.0 — so no valid install ever
+# has two declarers of it. `hwpx-conformance` is gone too: its package is
+# repository QA and no longer ships, and a console script pointing into an
+# excluded package would install as a command that cannot start.
 hwpx-unpack = "hwpx.tools.archive_cli:unpack_main"
 hwpx-pack = "hwpx.tools.archive_cli:pack_main"
 hwpx-validate = "hwpx.tools.validator:main"
@@ -78,33 +86,52 @@ hwpx-page-guard = "hwpx.tools.page_guard:main"
 hwpx-analyze-template = "hwpx.tools.template_analyzer:main"
 hwpx-text-extract = "hwpx.tools.text_extract_cli:main"
 hwpx-repair = "hwpx.tools.repair:main"
-hwpx-conformance = "hwpx.conformance.runner:main"
 
 [tool.setuptools]
 package-dir = { "" = "src" }
 include-package-data = true
+# Namespace-aware discovery. hwpx/opc and hwpx/data carry no __init__.py, so a
+# plain find_packages misses them, and they only ever shipped because
+# include-package-data swept them in as data files of hwpx. That same sweep kept
+# hwpx/benchmark and hwpx/conformance in the wheel after they were excluded from
+# the package list — one mechanism, helping in one place and hurting in the other.
+# The list is deliberately exact. A wildcard made any new directory below
+# ``src/hwpx`` publishable without a packaging review, which is the opposite of
+# the library/application boundary. Namespace packages (``opc`` and ``data``)
+# are valid explicit entries.
+packages = [
+    "hwpx",
+    "hwpx._document",
+    "hwpx.data",
+    "hwpx.equation",
+    "hwpx.form_fit",
+    "hwpx.ingest",
+    "hwpx.layout",
+    "hwpx.opc",
+    "hwpx.oxml",
+    "hwpx.quality",
+    "hwpx.tools",
+    "hwpx.tools._schemas",
+]
 
-[tool.setuptools.packages.find]
-where = ["src"]
-include = ["hwpx*"]
+# Only packages that ship. A key here for an excluded or deleted package pulls it
+# back into the wheel: hwpx.conformance was excluded from packages.find and still
+# shipped because this table named it, and hwpx.design no longer exists at all.
 
+# Listed explicitly rather than discovered with an exclude pattern. The exclude
+# form silently failed to keep hwpx.benchmark and hwpx.conformance out of the
+# wheel, and a packaging rule that looks right while shipping the opposite is
+# worse than a longer list. Adding a package here is a deliberate act.
 [tool.setuptools.package-data]
 "hwpx" = ["py.typed"]
 "hwpx.tools" = ["_schemas/*.xsd"]
 "hwpx.data" = ["Skeleton.hwpx"]
-"hwpx.visual" = ["_render_hwpx.ps1", "_render_hwpx_mac.applescript", "_refresh_hwpx_mac.applescript", "_hancom_open_rate.ps1"]
-"hwpx.design" = [
-    "profiles/*/profile.json",
-    "profiles/*/template.hwpx",
-    "profiles/*/fragments/*.xml",
-]
-"hwpx.conformance" = [
-    "corpus/corpus.json",
-    "corpus/*.hwpx",
-]
 
 [tool.pytest.ini_options]
-pythonpath = ["src"]
+# scripts/ carries repository QA harnesses that are not library surface — the
+# fuzz loop moved there in 5.0 because it needs the MCP owner's builder, and
+# core must never import a companion layer.
+pythonpath = ["src", "scripts"]
 addopts = "-ra"
 testpaths = ["tests"]
 
@@ -124,6 +151,8 @@ files = [
     "src/hwpx/equation/mathml.py",
     "src/hwpx/equation/render.py",
     "src/hwpx/tools/document_viewer.py",
+    "src/hwpx/tools/mail_merge.py",
+    "src/hwpx/tools/redline.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",
@@ -132,9 +161,6 @@ files = [
     "src/hwpx/_document/persistence.py",
     "src/hwpx/_document/shapes.py",
     "src/hwpx/_document/tracked.py",
-    "src/hwpx/agent/commands.py",
-    "src/hwpx/agent/document.py",
-    "src/hwpx/agent/story.py",
     "src/hwpx/oxml/_document_impl.py",
     "src/hwpx/oxml/_document_primitives.py",
     "src/hwpx/oxml/document.py",
@@ -153,6 +179,7 @@ files = [
     "src/hwpx/oxml/simple_parts.py",
     "src/hwpx/oxml/table.py",
     "src/hwpx/quality/policy.py",
+    "src/hwpx/quality/rendering.py",
     "src/hwpx/quality/report.py",
     "src/hwpx/tools/archive_cli.py",
     "src/hwpx/tools/package_validator.py",
@@ -160,7 +187,6 @@ files = [
     "src/hwpx/tools/template_analyzer.py",
     "src/hwpx/tools/text_extract_cli.py",
     "src/hwpx/tools/text_extractor.py",
-    "src/hwpx/visual/oracle.py",
     "tests/template_automation/helpers.py",
     "tests/template_automation/generate_fixtures.py",
 ]
@@ -179,6 +205,8 @@ include = [
     "src/hwpx/equation/mathml.py",
     "src/hwpx/equation/render.py",
     "src/hwpx/tools/document_viewer.py",
+    "src/hwpx/tools/mail_merge.py",
+    "src/hwpx/tools/redline.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",
@@ -187,9 +215,6 @@ include = [
     "src/hwpx/_document/persistence.py",
     "src/hwpx/_document/shapes.py",
     "src/hwpx/_document/tracked.py",
-    "src/hwpx/agent/commands.py",
-    "src/hwpx/agent/document.py",
-    "src/hwpx/agent/story.py",
     "src/hwpx/oxml/_document_impl.py",
     "src/hwpx/oxml/_document_primitives.py",
     "src/hwpx/oxml/document.py",
@@ -208,6 +233,7 @@ include = [
     "src/hwpx/oxml/simple_parts.py",
     "src/hwpx/oxml/table.py",
     "src/hwpx/quality/policy.py",
+    "src/hwpx/quality/rendering.py",
     "src/hwpx/quality/report.py",
     "src/hwpx/tools/archive_cli.py",
     "src/hwpx/tools/package_validator.py",
@@ -215,7 +241,6 @@ include = [
     "src/hwpx/tools/template_analyzer.py",
     "src/hwpx/tools/text_extract_cli.py",
     "src/hwpx/tools/text_extractor.py",
-    "src/hwpx/visual/oracle.py",
     "tests/template_automation/helpers.py",
     "tests/template_automation/generate_fixtures.py",
 ]