Metadata-Version: 2.4
Name: hwpapi
Version: 2.0.0
Summary: Pythonic HWP(한컴 오피스) automation via win32com — slim App facade + doc.collections + hwpapi.low escape hatch
Author-email: JunDamin <freedomgod@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://JunDamin.github.io/hwpapi
Project-URL: Repository, https://github.com/JunDamin/hwpapi
Project-URL: Documentation, https://JunDamin.github.io/hwpapi
Project-URL: Issues, https://github.com/JunDamin/hwpapi/issues
Project-URL: Changelog, https://github.com/JunDamin/hwpapi/blob/main/CHANGELOG.md
Keywords: hwp,hancom,korean-word-processor,python,win32com,automation,office
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: Korean
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
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: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pywin32
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: PyMuPDF>=1.23; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: PyMuPDF>=1.23; extra == "test"
Provides-Extra: docs
Requires-Dist: matplotlib; extra == "docs"
Requires-Dist: quartodoc; extra == "docs"
Requires-Dist: griffe<1.0; extra == "docs"
Requires-Dist: jupyter; extra == "docs"
Dynamic: license-file

# hwpapi

[![PyPI](https://img.shields.io/pypi/v/hwpapi.svg)](https://pypi.org/project/hwpapi/)
[![Python](https://img.shields.io/pypi/pyversions/hwpapi.svg)](https://pypi.org/project/hwpapi/)
[![License](https://img.shields.io/pypi/l/hwpapi.svg)](https://github.com/JunDamin/hwpapi/blob/main/LICENSE)
[![Docs](https://img.shields.io/badge/docs-JunDamin.github.io-2780E3)](https://JunDamin.github.io/hwpapi)
[![Status](https://img.shields.io/badge/status-v2.0-success)](https://github.com/JunDamin/hwpapi)

**한글(HWP) 자동화를 위한 Pythonic 라이브러리.** `hwpapi.App` 슬림 퍼사드 +
`app.doc.*` 컬렉션 + `hwpapi.low.*` escape hatch 의 이중 레이어 API.

> 📖 **전체 문서는 [JunDamin.github.io/hwpapi](https://JunDamin.github.io/hwpapi)**
> — 설치 · 5분 투어 · Guide · Recipes · API Reference · v1 → v2 마이그레이션.

---

## Requirements

- **Windows** + 한컴 오피스 설치
- **Python 3.9+**
- `pywin32`

## Install

```sh
pip install hwpapi
```

## 5분 투어

```python
from hwpapi import App

app = App()                                   # HWP 연결
app.open("report.hwp")

# 컬렉션 — dict-like + iterable + filterable
app.doc.fields["name"] = "홍길동"
app.doc.bookmarks.add("ch1")
for tbl in app.doc.tables:
    print(tbl.caption, tbl.rows, "×", tbl.cols)

# 문단/런
for para in app.doc.paragraphs:
    print(para.style, "|", para.text[:40])

# Escape hatch — 저수준 actions / parametersets / engine
from hwpapi.low import actions, parametersets
char = parametersets.CharShape(app.actions.CharShape.pset)
char.bold = True
actions.CharShape(app).execute(char)

app.save()
```

더 많은 예제는 [Recipes](https://JunDamin.github.io/hwpapi/recipes/) 를 참고하세요.

---

## v1 → v2 변경점

v2 는 **public API break** 를 허용한 클린컷 릴리즈입니다.

| v1.x | v2.0 |
|---|---|
| `from hwpapi.core import App` | `from hwpapi import App` |
| `app.fields[...]` | `app.doc.fields[...]` |
| `app.bookmarks`, `app.images`, ... | `app.doc.bookmarks`, `app.doc.images`, ... |
| `app.charshape = {...}` | `with hwpapi.context.charshape_scope(app, bold=True): ...` |
| `app.preset.*`, `app.template.*` | *(Phase-out — Recipes 페이지에서 레시피 형태로 재공급)* |
| `hwpapi.parametersets` | `hwpapi.low.parametersets` |

전체 매핑 80+ 항목: [Migration Guide](https://JunDamin.github.io/hwpapi/getting-started/migration-v1-to-v2.html)

v1.x 에 머무르려면 `pip install "hwpapi<2"` 또는 `git checkout v1.x`.

---

## 기여

- 이슈/PR: [github.com/JunDamin/hwpapi](https://github.com/JunDamin/hwpapi)
- 아키텍처/의사결정: [docs/design/adr/](https://JunDamin.github.io/hwpapi/design/)

## License

MIT
