syhwp 0.0.5__tar.gz

syhwp-0.0.5/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[test]"
+      - name: Test
+        run: pytest -q

syhwp-0.0.5/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+# Publishes to PyPI when a GitHub Release is published, using PyPI Trusted
+# Publishing (OIDC) — no API token or secret is stored anywhere.
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/):
+#   Add a pending publisher with
+#     PyPI project name: syhwp
+#     Owner:             sysphere
+#     Repository name:   syhwp
+#     Workflow name:     publish.yml
+#     Environment name:  pypi
+# Then create a GitHub Release (tag e.g. v0.0.5) to trigger this workflow.
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/syhwp
+    permissions:
+      id-token: write   # OIDC token for PyPI trusted publishing
+      contents: read    # allow actions/checkout to read the (private) repo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

syhwp-0.0.5/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Test / tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local sample documents (do not commit copyrighted files)
+tests/data/*.hwp
+tests/data/*.hwpx
+!tests/data/.gitkeep
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

syhwp-0.0.5/CLAUDE.md

@@ -0,0 +1,76 @@
+# syhwp
+
+Korean **HWP 5.x** / **HWPX** 문서를 텍스트·마크다운으로 추출하는 순수 파이썬 라이브러리.
+permissive(MIT) 라이선스로, AGPL(`pyhwp`)·미유지 바인딩(`libhwp`)의 공백을 메운다.
+
+## ⚠️ 최우선 규칙: 클린룸 provenance
+
+**이 프로젝트의 존재 이유가 permissive 라이선스다. 절대 깨지 말 것:**
+
+- 구현은 **오직 Hancom 공개 스펙**(HWP 5.0 바이너리 포맷, OWPML)에서만 도출한다.
+- **AGPL인 `pyhwp` 소스를 참고/복사하지 않는다.** (참고하는 순간 MIT 공개가 위반)
+- Apache인 `hwp.js`/`hwp-rs`는 동작 교차검증용으로만 볼 수 있고, 실질 복제 시 Apache-2.0
+  + NOTICE 승계 의무가 생기므로 코드 이식은 피한다. 스펙에서 직접 구현.
+- 새 레코드/구조를 추가할 때 근거(스펙 절/필드)를 커밋 메시지나 주석에 남긴다.
+
+## 개발 명령어
+
+```bash
+pip install -e ".[test]"     # 개발 설치 (의존성: olefile 하나)
+pytest -q                    # 전체 테스트
+pytest tests/test_records.py # 단위 테스트만
+python -c "import syhwp; print(syhwp.extract_markdown('sample.hwpx'))"
+```
+
+로컬 실측용 실제 문서는 `tests/data/`에 두면 되지만 **커밋 금지**(.gitignore 처리,
+저작권). 합성 샘플 기반 테스트만 리포에 포함한다.
+
+## 아키텍처
+
+```
+src/syhwp/
+  __init__.py    공개 API: detect_format / extract_text / extract_markdown (포맷 자동 감지)
+  exceptions.py  SyhwpError ← UnsupportedFormatError / InvalidHwpError / EncryptedDocumentError
+  _records.py    HWP5 레코드 순회 (헤더 uint32: tag10b/level10b/size12b, 0xFFF 확장)
+  _hwp5.py       HWP5(OLE) 리더 — FileHeader 플래그, zlib(-15) 해제, PARA_TEXT(67) 디코드
+  _hwpx.py       HWPX(OWPML) 리더 — zipfile+ElementTree, local-name 매칭, 표→GFM
+  _markdown.py   GFM 표 렌더 공용 (normalize / escape_cell / grid_to_markdown)
+```
+
+### 핵심 포맷 사실 (자주 참조)
+
+- **HWP5 = OLE 복합파일**(magic `D0CF11E0`). 스트림: `FileHeader`, `BodyText/Section{N}`,
+  `DocInfo`(스타일 — **텍스트/표 추출엔 불필요, 파싱 안 함** → libhwp가 죽는 지점을 우회),
+  `PrvText`(무압축 UTF-16LE 미리보기 지름길).
+- FileHeader offset 36 properties 플래그: bit0 압축, bit1 암호, bit2 배포용. bit1/2면
+  본문 암호화 → `EncryptedDocumentError`.
+- 압축 섹션은 raw DEFLATE: `zlib.decompress(data, -15)`.
+- PARA_TEXT 컨트롤 문자: 8 code-unit `{1-9,11,12,14-23}`, 1 unit `{0,10,13,24-31}`(10/13→개행).
+- **HWPX = ZIP**(magic `PK\x03\x04`, mimetype `application/hwp+zip`). 본문
+  `Contents/section{N}.xml`, 요소 로컬네임 `p/t/tbl/tr/tc`.
+
+## 코딩 컨벤션
+
+- 순수 파이썬, 외부 의존성은 **`olefile`(BSD)** 만. HWPX는 stdlib만.
+- **견고성 우선**: 미지 레코드/요소는 raise 말고 skip. 잘린 스트림도 graceful.
+  (패닉/크래시 없는 게 libhwp 대비 핵심 차별점)
+- 예외는 전부 `SyhwpError` 하위. 사용자에게 명확한 사유 메시지.
+- 공개 API는 `__init__.py`의 `__all__`만. 내부 모듈은 `_` 접두.
+- Python 3.9+ 호환 (타입힌트 `List`/`Iterator` from typing, `X | Y` 지양).
+
+## 로드맵 (DESIGN.md 상세)
+
+- **v0 (완료)**: 포맷감지 + HWP5 텍스트 + HWPX 텍스트/표 + 암호감지.
+- **v0.1 (완료)**: HWP5 **표 그리드 재구성** — 레코드 level 트리 + CTRL_HEADER(`tbl `,
+  파일에선 `b" lbt"`) + TABLE(77: nRows@4/nCols@6) + 셀 LIST_HEADER(72: nPara@0/
+  col@8/row@10/span@12,14) 그룹핑 → GFM. 중첩표는 셀 텍스트로 linearize.
+- **v0.2 (완료)**: 구조화 API `open() → Document`(.paragraphs/.tables),
+  Table(n_rows/n_cols/cells)·Cell(row/col/row_span/col_span/text). 병합셀 span은
+  모델에 포착(GFM 출력은 병합 불가라 빈칸 유지).
+- **v0.3 (진행)**: ✅ 버전 캡처(Document.version) ✅ 인라인 개체(수식 스크립트 `[수식:]`,
+  그림 `[그림]`, 셀 내부 포함) ✅ 퍼즈/방어 하드닝(OLE/zip 오류·압축폭탄→SyhwpError).
+  ⏳ 각주/미주(샘플 없어 보류) ⏳ 문자서식→마크다운 강조 ⏳ 실 코퍼스.
+
+## 비목표
+
+쓰기/편집, 레이아웃 픽셀 충실도, 암호문서 복호화, HWP 3.x(구포맷).

syhwp-0.0.5/DESIGN.md

@@ -0,0 +1,139 @@
+# syhwp — Design
+
+## Goal
+
+A pure-Python, permissively licensed reader for Korean HWP 5.x (legacy binary)
+and HWPX (OWPML) documents, producing plain text and GFM markdown (tables as
+pipe tables). Primary use case: feeding Korean office documents into RAG /
+search / LLM pipelines where AGPL (`pyhwp`) and brittle/unmaintained bindings
+(`libhwp`) are not acceptable.
+
+Design priorities, in order: **(1) permissive license, (2) robustness on
+real-world files, (3) zero-friction deployment (pure Python, one BSD dep),
+(4) fidelity (tables).**
+
+## Clean-room provenance
+
+Implemented solely from HANCOM's published specifications:
+- *한글 문서 파일 형식 5.0* (HWP 5.0 binary record format) — OLE/CFBF container,
+  record stream layout, control characters.
+- *OWPML* (HWPX) — OPC/ZIP package, section XML.
+
+No code or structure is taken from the AGPL `pyhwp`. Apache-licensed references
+(`hwp.js`, `hwp-rs`) may be consulted for cross-checking behaviour only; any
+substantial reuse would require carrying Apache-2.0 + NOTICE, which we avoid by
+working from the spec. This provenance is what permits the MIT license.
+
+## Formats
+
+### HWP 5.x (`_hwp5.py`)
+OLE compound file (magic `D0CF11E0…`). Relevant streams:
+- `FileHeader` — 32-byte signature `"HWP Document File"`, then version (uint32)
+  and properties (uint32). Property bit 0 = compressed, bit 1 = password,
+  bit 2 = distribution (copy-protected). Bits 1/2 ⇒ body is encrypted ⇒ we raise
+  `EncryptedDocumentError`.
+- `BodyText/Section{N}` — the content. If compressed, raw DEFLATE
+  (`zlib.decompress(data, -15)`).
+- `DocInfo` — styles / char shapes / bindata map. **Not required for text or
+  table extraction**, so we do not parse it. (This is a robustness win: `libhwp`
+  panics inside DocInfo style parsing on files we read fine.)
+
+**Records** (`_records.py`): each record is a uint32 header —
+`tag = bits 0–9`, `level = bits 10–19`, `size = bits 20–31`; if `size == 0xFFF`
+the real size is the following uint32 — then `size` bytes of payload. Unknown
+tags are skipped.
+
+**Text** (`HWPTAG_PARA_TEXT`, tag 67): UTF-16LE code units with inline control
+characters. Control chars occupying 8 code units (extended/inline objects):
+`{1–9, 11, 12, 14–23}`; occupying 1 unit (char controls): `{0, 10, 13, 24–31}`,
+of which 10/13 map to a newline. Everything else is literal text.
+
+**Tables** are reconstructed from the record tree (built from each record's
+`level`). A table is a `HWPTAG_CTRL_HEADER` (tag 71) whose first 4 payload bytes
+are the little-endian control id `"tbl "` (i.e. `b" lbt"`). Its children are:
+- `HWPTAG_TABLE` (tag 77): `n_rows` (uint16 @4), `n_cols` (uint16 @6).
+- repeated `HWPTAG_LIST_HEADER` (tag 72) — one per cell: `n_paragraphs`
+  (uint16 @0), then `col`/`row`/`col_span`/`row_span` (uint16 @8/@10/@12/@14) —
+  each followed by its `n_paragraphs` `HWPTAG_PARA_HEADER` (tag 66) subtrees,
+  which hold the cell's text. Cells are placed into a `n_rows × n_cols` grid and
+  rendered as GFM. Nested tables (a table inside a cell) linearize into that
+  cell's text. (Offsets were derived empirically from the public format, not
+  from `pyhwp` — see the clean-room note.)
+
+### HWPX (`_hwpx.py`)
+ZIP package (magic `PK\x03\x04`, mimetype `application/hwp+zip`). Text and tables
+live in `Contents/section{N}.xml` as OWPML. Parsed with the standard library
+(`zipfile` + `xml.etree.ElementTree`), matching elements by local name
+(namespace-agnostic): `p` (paragraph), `t` (text run), `tbl`/`tr`/`tc`
+(table/row/cell), `equation` (with `script`), `pic` (image). Tables render to
+GFM via `_markdown.py`; version comes from `version.xml`
+(major.minor.micro.buildNumber).
+
+## Public API (`__init__.py`)
+- `detect_format(path) -> "hwp5" | "hwpx"`
+- `extract_text(path) -> str`
+- `extract_markdown(path) -> str`
+
+## Roadmap
+- **v0 (done):** format detection; HWP5 text extraction; HWPX text + tables;
+  encryption detection. Verified on real government documents, including files
+  that crash `libhwp`.
+- **v0.1 (done):** HWP5 **table grid reconstruction** — walk the record tree by
+  `level`, detect `CTRL_HEADER` with ctrl-id `tbl `, read the `TABLE` record
+  (rows/cols) and per-cell `LIST_HEADER`, group cell paragraphs into a grid → GFM.
+- **v0.2 (done):** structured API — `open() -> Document` with `.paragraphs` /
+  `.tables`; `Table` (`n_rows`, `n_cols`, `cells`), `Cell` (`row`, `col`,
+  `row_span`, `col_span`, `text`). `col_span`/`row_span` are captured in the
+  model (GFM output still leaves merged slots blank — GFM cannot merge cells).
+### Enhancement roadmap (prioritized for RAG / document ingestion)
+
+`syhwp` is an *extraction* library, not a full-fidelity converter like pyhwp's
+ODT path. The gaps that matter for the RAG use case, in priority order:
+
+**Tier 1 — coverage & robustness**
+- ✅ **Version-aware parsing** — FileHeader version captured on `Document.version`
+  (field-offset branching per sub-version to follow as older files surface).
+- ✅ **Inline objects** — equations → their script (`[수식: …]`), images/drawing
+  objects → `[그림]`, at top level and inside table cells.
+- ✅ **Fuzz / defensive hardening** — corrupt OLE/zip, decompression bombs, and
+  truncated streams raise `SyhwpError` instead of crashing (fuzz-tested).
+- ⏳ **Footnotes / endnotes & captions** — deferred: no sample document with
+  footnotes on hand to verify against; emit `[^n]` markers once one is obtained.
+- ⏳ **Char-shape → markdown emphasis** — parse DocInfo char shapes to emit
+  `**bold**` / `*italic*`.
+- ✅ **Corpus harness** — `tests/test_corpus.py` runs over real documents placed
+  in `tests/data/` (gitignored); skips in CI. Exercised on 22 varied HWP/HWPX
+  files (multiple versions incl. 5.0.2.x, equations, images, tables, and two
+  distribution-protected files that correctly raise `EncryptedDocumentError`).
+
+**Tier 2 — high value, higher effort**
+- **Distribution (배포용) document decoding** — *deferred, not guessed.* Confirmed
+  two protected samples (FileHeader distribution bit set; the section stream is
+  obfuscated from byte 0, seed at bytes[0:4]). Correctly rejected today with
+  `EncryptedDocumentError` (no crash). Real decoding needs the authoritative
+  HANCOM distribution-doc spec (seed → LCG de-obfuscation → AES-128 key) plus an
+  AES backend — implemented clean-room from the spec and verified against the
+  samples, not reverse-engineered by guesswork. AES would be an optional extra
+  (`syhwp[crypto]`) to keep the core dependency-free.
+- Nested-table rendering (HTML / indented), HWPX cell spans & images.
+
+**Tier 3 — convenience / fidelity**
+- ✅ `extract_html()` / `Document.html`; ✅ CLI (`syhwp` / `python -m syhwp`,
+  `--text/--markdown/--html`); ✅ `py.typed`.
+- ⏳ hyperlinks → markdown links, streaming.
+
+**Quality (feature-independent):** decompression-bomb & recursion-depth guards,
+benchmarks vs pyhwp / libhwp (speed + coverage on a corpus).
+
+### vs pyhwp — where syhwp already differs
+Ahead: MIT (vs AGPL); HWPX support (pyhwp is HWP5-only); markdown output;
+robustness (skips DocInfo styling, the area that crashes libhwp; unknown records
+are skipped, not fatal); pure Python, one BSD dep, 3.9–3.13.
+Behind: distribution-doc decoding, rich styles/images/equations, footnotes,
+version-specific coverage, and 15 years of real-file maturity.
+
+## Non-goals
+- Writing/editing HWP files (read-only).
+- Rendering/layout fidelity (we target content extraction, not pixel fidelity).
+- Decrypting password/distribution-protected documents.
+- HWP 3.x and earlier (different, pre-5.0 format).

syhwp-0.0.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sysphere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

syhwp-0.0.5/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: syhwp
+Version: 0.0.5
+Summary: Pure-Python reader for Korean HWP 5.x and HWPX documents — text and tables. Clean-room, permissively licensed.
+Project-URL: Homepage, https://github.com/sysphere/syhwp
+Project-URL: Source, https://github.com/sysphere/syhwp
+Project-URL: Issues, https://github.com/sysphere/syhwp/issues
+Author: sysphere
+License: MIT
+License-File: LICENSE
+Keywords: hancom,hwp,hwpx,korean,parser,rag,text-extraction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Korean
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Text Processing :: Markup
+Requires-Python: >=3.9
+Requires-Dist: olefile>=0.46
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# syhwp
+
+Pure-Python reader for Korean **HWP 5.x** and **HWPX** documents — extracts text
+and tables, with no external services and a permissive license.
+
+```python
+import syhwp
+
+# convenience
+text = syhwp.extract_text("report.hwp")        # plain text
+md   = syhwp.extract_markdown("report.hwpx")   # GFM markdown (tables as pipe tables)
+
+# structured access
+doc = syhwp.open("report.hwp")                 # -> Document
+for table in doc.tables:                       # Table: n_rows, n_cols, cells[...]
+    print(table.to_markdown())
+for para in doc.paragraphs:                     # Paragraph: text
+    print(para.text)
+```
+
+Format (HWP vs HWPX) is auto-detected. Works the same for `.hwp` and `.hwpx`.
+
+Also available as a command line tool:
+
+```bash
+syhwp report.hwp                 # markdown (default); also --text / --html
+python -m syhwp report.hwpx
+```
+
+## Why
+
+The existing Python options each have a blocking flaw for use in commercial or
+SaaS software:
+
+| Library | License | Issue |
+|---|---|---|
+| `pyhwp` | **AGPL-3.0** | Strong network copyleft — unusable in closed/SaaS products |
+| `libhwp` (hwp-rs) | Apache-2.0 | Unmaintained (0.2.0), panics on real files, no 3.12+ wheels |
+| `pyhwpx` | — | Windows-only (COM automation) |
+
+`syhwp` fills the gap: **pure Python, permissive (MIT), maintained, robust by
+design** (unknown/edge records are skipped rather than crashing).
+
+## Install
+
+```bash
+pip install syhwp
+```
+
+Only dependency: [`olefile`](https://pypi.org/project/olefile/) (BSD). HWPX
+parsing uses the standard library only.
+
+## Status
+
+Alpha. See [DESIGN.md](DESIGN.md) for the architecture and roadmap.
+
+- **HWP 5.x** — text and table extraction (tables reconstructed into GFM pipe
+  tables); equations surfaced as their script, images/drawings as `[그림]`;
+  document version exposed on `Document.version`.
+- **HWPX** — text and table extraction.
+- Robust by design: unknown records are skipped, and malformed / corrupt files
+  raise a `SyhwpError` subclass rather than crashing (fuzz-tested).
+- Password-protected / distribution (copy-protected) documents raise
+  `EncryptedDocumentError` (their body streams are encrypted and cannot be read).
+
+## Provenance / license note
+
+`syhwp` is a **clean-room implementation** written from the publicly published
+HANCOM *HWP 5.0 binary format* and *OWPML (HWPX)* specifications. It does **not**
+derive from, or incorporate code from, the AGPL-licensed `pyhwp`. This is what
+allows `syhwp` to be offered under the permissive MIT license.
+
+## License
+
+MIT © 2026 sysphere

syhwp-0.0.5/README.md

@@ -0,0 +1,75 @@
+# syhwp
+
+Pure-Python reader for Korean **HWP 5.x** and **HWPX** documents — extracts text
+and tables, with no external services and a permissive license.
+
+```python
+import syhwp
+
+# convenience
+text = syhwp.extract_text("report.hwp")        # plain text
+md   = syhwp.extract_markdown("report.hwpx")   # GFM markdown (tables as pipe tables)
+
+# structured access
+doc = syhwp.open("report.hwp")                 # -> Document
+for table in doc.tables:                       # Table: n_rows, n_cols, cells[...]
+    print(table.to_markdown())
+for para in doc.paragraphs:                     # Paragraph: text
+    print(para.text)
+```
+
+Format (HWP vs HWPX) is auto-detected. Works the same for `.hwp` and `.hwpx`.
+
+Also available as a command line tool:
+
+```bash
+syhwp report.hwp                 # markdown (default); also --text / --html
+python -m syhwp report.hwpx
+```
+
+## Why
+
+The existing Python options each have a blocking flaw for use in commercial or
+SaaS software:
+
+| Library | License | Issue |
+|---|---|---|
+| `pyhwp` | **AGPL-3.0** | Strong network copyleft — unusable in closed/SaaS products |
+| `libhwp` (hwp-rs) | Apache-2.0 | Unmaintained (0.2.0), panics on real files, no 3.12+ wheels |
+| `pyhwpx` | — | Windows-only (COM automation) |
+
+`syhwp` fills the gap: **pure Python, permissive (MIT), maintained, robust by
+design** (unknown/edge records are skipped rather than crashing).
+
+## Install
+
+```bash
+pip install syhwp
+```
+
+Only dependency: [`olefile`](https://pypi.org/project/olefile/) (BSD). HWPX
+parsing uses the standard library only.
+
+## Status
+
+Alpha. See [DESIGN.md](DESIGN.md) for the architecture and roadmap.
+
+- **HWP 5.x** — text and table extraction (tables reconstructed into GFM pipe
+  tables); equations surfaced as their script, images/drawings as `[그림]`;
+  document version exposed on `Document.version`.
+- **HWPX** — text and table extraction.
+- Robust by design: unknown records are skipped, and malformed / corrupt files
+  raise a `SyhwpError` subclass rather than crashing (fuzz-tested).
+- Password-protected / distribution (copy-protected) documents raise
+  `EncryptedDocumentError` (their body streams are encrypted and cannot be read).
+
+## Provenance / license note
+
+`syhwp` is a **clean-room implementation** written from the publicly published
+HANCOM *HWP 5.0 binary format* and *OWPML (HWPX)* specifications. It does **not**
+derive from, or incorporate code from, the AGPL-licensed `pyhwp`. This is what
+allows `syhwp` to be offered under the permissive MIT license.
+
+## License
+
+MIT © 2026 sysphere

syhwp-0.0.5/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "syhwp"
+version = "0.0.5"
+description = "Pure-Python reader for Korean HWP 5.x and HWPX documents — text and tables. Clean-room, permissively licensed."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "sysphere" }]
+keywords = ["hwp", "hwpx", "hancom", "korean", "parser", "text-extraction", "rag"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: Korean",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = ["olefile>=0.46"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+syhwp = "syhwp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/sysphere/syhwp"
+Source = "https://github.com/sysphere/syhwp"
+Issues = "https://github.com/sysphere/syhwp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/syhwp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

syhwp-0.0.5/src/syhwp/__init__.py

@@ -0,0 +1,80 @@
+"""syhwp — pure-Python reader for Korean HWP 5.x and HWPX documents.
+
+Clean-room implementation from the public HANCOM HWP 5.0 / OWPML specifications.
+No AGPL, no external services. See DESIGN.md for architecture and provenance.
+
+    import syhwp
+    doc = syhwp.open("report.hwp")      # -> Document (paragraphs, tables)
+    text = syhwp.extract_text("report.hwp")
+    md   = syhwp.extract_markdown("report.hwpx")
+"""
+
+import io
+
+from .exceptions import (
+    EncryptedDocumentError,
+    InvalidHwpError,
+    SyhwpError,
+    UnsupportedFormatError,
+)
+from .models import Cell, Document, Equation, Image, Paragraph, Table
+
+__version__ = "0.0.5"
+
+__all__ = [
+    "open",
+    "detect_format",
+    "extract_text",
+    "extract_markdown",
+    "extract_html",
+    "Document",
+    "Paragraph",
+    "Table",
+    "Cell",
+    "Equation",
+    "Image",
+    "SyhwpError",
+    "UnsupportedFormatError",
+    "InvalidHwpError",
+    "EncryptedDocumentError",
+]
+
+_OLE_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+_ZIP_MAGIC = b"PK\x03\x04"
+
+
+def detect_format(path) -> str:
+    """Return ``"hwp5"`` or ``"hwpx"`` by inspecting the file's magic bytes."""
+    with io.open(path, "rb") as f:  # io.open — module-level `open` is our API below
+        head = f.read(8)
+    if head.startswith(_OLE_MAGIC):
+        return "hwp5"
+    if head.startswith(_ZIP_MAGIC):
+        return "hwpx"
+    raise UnsupportedFormatError(f"Not an HWP or HWPX file: {path!r}")
+
+
+def open(path) -> Document:  # noqa: A001 - intentional module-level API (cf. tarfile.open)
+    """Parse an HWP 5.x or HWPX document into a :class:`Document`."""
+    if detect_format(path) == "hwp5":
+        from ._hwp5 import read_document_hwp5
+
+        return read_document_hwp5(path)
+    from ._hwpx import read_document_hwpx
+
+    return read_document_hwpx(path)
+
+
+def extract_text(path) -> str:
+    """Extract plain text from an HWP 5.x or HWPX document."""
+    return open(path).text
+
+
+def extract_markdown(path) -> str:
+    """Extract GFM markdown (tables as pipe tables) from HWP 5.x or HWPX."""
+    return open(path).markdown
+
+
+def extract_html(path) -> str:
+    """Extract a standalone HTML document (tables as ``<table>``) from HWP/HWPX."""
+    return open(path).html