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
