pyhwpx: Python HWP Automation Module

1.7.2 · active · verified Thu Apr 16

pyhwpx is a Python module designed for automating Hancom HWP (Hangul Word Processor) documents. It leverages the `pywin32` package to interact with the HWP Automation API, providing a more intuitive and Pythonic interface compared to direct `win32com` usage. The library supports various document manipulation tasks such as text insertion, saving, and editing, and aims to add more shortcut methods for common HWP automation patterns. It is actively developed, with a current version of 1.7.2, and requires Python 3.9+ on a Windows operating system with Hancom HWP installed.

Common errors

```
ModuleNotFoundError: No module named 'pyhwpx'
```
cause The `pyhwpx` package is not installed in the current Python environment, or the environment is not activated.

fix Run `pip install pyhwpx` to install the library. Ensure your Python environment is correctly activated if using virtual environments.
```
pywintypes.com_error: (-2147352567, 'Exception occurred.', (...))
```
cause This generic COM error typically indicates that Hancom HWP is not running, not properly installed, or an invalid API call was made to the HWP application. It can also occur if `pywin32` is not correctly installed or configured.

fix Verify that Hancom HWP is installed and accessible on your system. Ensure `pywin32` is installed via `pip install pywin32`. Review the `pyhwpx` method call for correctness, paying attention to parameters and HWP's state.
```
AttributeError: 'Hwp' object has no attribute 'some_method_name'
```
cause You are attempting to call a method or access an attribute that does not exist or has an incorrect casing. `pyhwpx` uses a mixed naming convention (PascalCase for HWP API wrappers, snake_case for custom methods).

fix Check the `pyhwpx` documentation or source code for the exact method name and its correct casing (e.g., `InsertText` vs. `insert_text`).

Warnings

breaking pyhwpx is a Windows-only library and requires Hancom HWP (Hangul Word Processor) software to be installed on the system to function, as it relies on COM automation. It will not work on Linux, macOS, or without HWP installed.
Fix: Ensure you are running on a Windows OS with Hancom HWP installed.
gotcha The library uses a mixed naming convention: PascalCase for methods directly wrapping HWP Automation API functions and snake_case for custom utility methods. This can lead to `AttributeError` if the wrong casing is used.
Fix: Refer to the documentation or source code for the correct casing of specific methods. Prioritize PascalCase for direct HWP API calls.
breaking Version 1.0.0 introduced significant internal module reorganization (e.g., separation into `core`, `param_helpers`, `run_methods`). Code written for pre-1.0.0 versions may break due to changed import paths or internal structures.
Fix: Update your code to align with the new module structure and API changes introduced in version 1.0.0 and later.
breaking The `hwp.find` method had its `SeveralWords` parameter's default value changed from 1 to 0, and `FindString` became an optional parameter in version 1.2.1. This can alter the behavior of existing search logic.
Fix: Explicitly set `SeveralWords=1` if you rely on the old behavior, and adjust `FindString` usage as needed.

Install

pip install pyhwpx Install pyhwpx

Imports

Hwp
```
from pyhwpx import Hwp
```

Quickstart

Initializes an HWP automation object, inserts text, saves the document, and then closes HWP. Ensure Hancom HWP is installed on your Windows machine.

from pyhwpx import Hwp

# Connects to the most recently active HWP window.
# If HWP is not running, it launches a new instance.
hwp = Hwp()

# Insert text into the document
hwp.insert_text("Hello world from pyhwpx!")

# Save the document
hwp.save_as("./helloworld.hwp")

# Quit HWP
hwp.Quit()

view raw JSON →