Metadata-Version: 2.4
Name: jakal-hwpx
Version: 0.1.0
Summary: Round-trip safe HWPX reader/editor/writer for Python
Author: Ahnd6474
License-Expression: MIT
Project-URL: Homepage, https://github.com/Ahnd6474/jakal-hwpx
Project-URL: Source, https://github.com/Ahnd6474/jakal-hwpx
Project-URL: Issues, https://github.com/Ahnd6474/jakal-hwpx/issues
Project-URL: Documentation, https://github.com/Ahnd6474/jakal-hwpx#readme
Project-URL: Releases, https://github.com/Ahnd6474/jakal-hwpx/releases
Keywords: hwpx,hancom,document,xml,library
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Editors :: Word Processors
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: lxml<6,>=5.0.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: setuptools>=77; extra == "dev"
Requires-Dist: tox>=4.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: setuptools>=77; extra == "release"
Requires-Dist: twine>=5.0; extra == "release"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Dynamic: license-file

# jakal-hwpx

Python tools for reading, editing, validating, and writing `HWPX` documents.

Korean overview: [README.ko.md](./README.ko.md)

## What This Repo Contains

- `src/jakal_hwpx`: the importable Python package
- `examples/samples`: sample `hwpx` and `hwp` documents used for local experimentation
- `examples/output_smoke`: committed smoke corpus for tests
- `examples/output`: showcase outputs generated from the smoke corpus
- `tools`: bundled Java-based `.hwp -> .hwpx` converter assets used by maintainer workflows

This README is intentionally repo-level. Detailed module and API notes live in [HWPX_MODULE.md](./HWPX_MODULE.md).

## Installation

You need Python 3.11 or newer.

Install from PyPI:

```bash
python -m pip install --upgrade pip
python -m pip install jakal-hwpx
```

Install from a local checkout:

```bash
python -m pip install --upgrade pip
python -m pip install .
```

For editable development mode:

```bash
python -m pip install -e .[dev]
```

The package name is `jakal-hwpx` and the import path is `jakal_hwpx`.

## Quick Start

```python
from jakal_hwpx import HwpxDocument

doc = HwpxDocument.blank()
doc.set_metadata(title="Example", creator="jakal-hwpx")
doc.set_paragraph_text(0, 0, "Hello HWPX")
doc.save("build/hello.hwpx")
```

For module-level usage, document parts, and editing helpers, see [HWPX_MODULE.md](./HWPX_MODULE.md).

## Repository Layout

```text
src/jakal_hwpx/          Python package
examples/samples/hwpx/   sample HWPX documents
examples/samples/hwp/    sample HWP documents
examples/output_smoke/   committed smoke corpus used by tests
examples/output/         generated showcase outputs
scripts/                 maintainer scripts
tools/                   bundled HWP conversion tooling
```

## Testing

Run the default test suite:

```bash
python -m pip install -e .[dev]
python -m pytest -q
```

The tests first look for samples in:

1. `JAKAL_HWPX_SAMPLE_DIR`
2. `all_hwpx_flat/`
3. `examples/output_smoke/`
4. `examples/output/`
5. `examples/samples/hwpx/`

## Sample Files

Repository sample inputs now live under `examples/samples/` instead of the repo root:

- `examples/samples/hwpx/`
- `examples/samples/hwp/`

Generated validation outputs belong under `build/validation/`.

## More Docs

- [HWPX_MODULE.md](./HWPX_MODULE.md): package structure, module roles, and API usage
- [examples/SHOWCASE.md](./examples/SHOWCASE.md): showcase generation workflow
- [RELEASING.md](./RELEASING.md): release checklist
- [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md): scope notes for sample files, bundled tools, and HWPX-related naming

## License

Original project-authored source code in this repository is available under the [MIT License](./LICENSE).

Sample documents, committed outputs, and bundled toolchain artifacts under `tools/` can be subject to separate rights or upstream licenses. See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) before redistributing those assets.
