Overview
Python python-hwpx Generates documents in HWPX format based on the library. It follows the OWPML (Open Word Processor Markup Language) standard and creates official documents, drafts, and reports compatible with Hancom Office (Hwp). It can convert existing HWP files to HWPX or extract text.
Trigger keywords
Hangul, hwpx, Araeahangul, Hancom, official document, draft, HWP conversion, Hangul document generation, HWPX editing
Workflow
Step 1: Analyze document requirements
After analyzing the user request, determine the task type:
- Create new HWPX: official documents, drafts, reports, meeting minutes
- Convert HWP → HWPX: convert older Hangul files to the latest format
- Text extraction: extract content from existing HWPX
- Fill in a form: preserve the template layout and modify only the content
Step 2: Check dependencies
# 필수 라이브러리 설치
pip install python-hwpx lxml
# 선택 사항 (HWP 바이너리 처리)
pip install olefile
Step 3: Generate document with python-hwpx
from hwpx import HwpxDocument
hwp = HwpxDocument.new()
# 단락 추가, 표 삽입, 서식 적용 (상세는 scripts/create_hwpx.py 참조)
hwp.save("output.hwpx")
Step 4: Validate OWPML structure
Verify that the generated HWPX file complies with the OWPML spec, and check that it opens correctly in Hancom Office.
Usage examples
- "Make a Hangul file requesting cooperation in the official document format"
- "Convert the existing HWP file to HWPX"
- "Write a proposal in the Araeahangul draft format"
- "Extract text from the HWPX file"
- "Verify that the Hangul document content has the correct OWPML structure"
Output format
- File format:
.hwpx(Hancom Office 2010+ standard) - Standard: OWPML 1.5 (Open Word Processor Markup Language)
- Compression: ZIP-based (XML + resource files)
- Hangul compatibility: opens correctly in Hancom Office 2014, 2018, and 2020
Precautions
Stable features vs limited features
| Feature | Status | Notes |
|---|---|---|
| Add paragraph | Stable | Basic feature |
| Bold/italic/underline | Stable | lxml patch applied automatically |
| Table | Stable | No row/column limit |
| Header/footer | Stable | - |
| Footnotes/endnotes | Stable | - |
| Bookmarks | Stable | - |
| Text replacement | Stable | - |
| Shapes (line/rectangle/ellipse) | Limited | May cause error warnings in Hangul |
| Insert image | Limitations | Incomplete pic element creation |
| Multi-column settings | Limitations | Error warnings may occur in Hangul |
Hancom Office environment
HWPX files open optimally in Hancom Office. In environments where Hancom Office is not installed, moai-office:docx-generator use of the skill is recommended.
Font compatibility
Hancom-exclusive fonts (HYHeadline, HYGothic, etc.) display correctly only in environments where Hancom Office is installed. When distributing, embedding fonts or converting to PDF is recommended.
HWP conversion limitations
Conversion limitations may apply depending on the HWP file version (2010/2014/2018, etc.). Older HWP versions may only support text extraction.
Troubleshooting
| Situation | Solution |
|---|---|
| File creation failed | Check whether python-hwpx and lxml are installed: pip install python-hwpx lxml. Retry after installation |
| HWPX library not installed | pip install python-hwpx After running, refer to the installation guide |
| HWP conversion error | Check the HWP file version (2010/2014/2018, etc.). Older versions may have conversion limitations |
| OWPML structure error | After validating with the validate.py script, share the error details and we will help fix it |
| Font corruption | Hancom-exclusive fonts (HYHeadline, HYGothic, etc.) display correctly only in environments where Hancom Office is installed |
| Does not open in Hangul | Check the OWPML namespace and verify that the xml header is correct |
Related skill / self-inspection
When Hangul document creation is finished, reopen the generated .hwpx file to check for remaining placeholders, OWPML structure, Hangul encoding corruption, and table corruption self-inspectionand, if there are issues, automatically fix and regenerate, then report the final PASS/FAIL result.
moai-office:docx-generator- Create DOCX (Word) documentmoai-office:pptx-designer- Create PPT slides for presentationmoai-office:xlsx-creator- Create Excel data sheet
Technical reference
- python-hwpx GitHub: https://github.com/airmang/python-hwpx
- OWPML spec: Hancom OWPML 1.5 specification
- Hancom Office API: HwpObject programming guide