hwpapi - Hancom Office (HWP) Python Automation Wrapper

# hwpapi - Hancom Office (HWP) Python Automation Wrapper

## Project Overview

hwpapi is a Python wrapper library that simplifies automation of Hancom Office (HWP - 한글, Korean word processor) using the win32com interface. It provides a Pythonic API for document manipulation, inspired by xlwings.

**Platform:** Windows only (requires win32com and HWP installed)
**Target Users:** Korean office workers automating HWP document processing
**Language:** Bilingual (Korean primary, English secondary)
**Version:** 0.0.2.2
**License:** MIT

## Critical Development Constraints

### nbdev Notebook-Driven Development

**CRITICAL:** This project uses nbdev - ALL source code lives in Jupyter notebooks in `nbs/` directory.

- **NEVER edit `.py` files in `hwpapi/` directory directly** - they are auto-generated from notebooks
- All `.py` files have `# AUTOGENERATED! DO NOT EDIT!` header
- To modify code: edit the corresponding `.ipynb` file in `nbs/`, then run `nbdev_export`
- Mapping:
  - `nbs/02_api/00_core.ipynb` → `hwpapi/core.py`
  - `nbs/02_api/01_actions.ipynb` → `hwpapi/actions.py`
  - `nbs/02_api/02_parameters.ipynb` → `hwpapi/parametersets.py`
  - `nbs/02_api/03_classes.ipynb` → `hwpapi/classes.py`
  - `nbs/02_api/04_constants.ipynb` → `hwpapi/constants.py`
  - `nbs/02_api/05_markdown_parser.ipynb` → (utilities)
  - `nbs/02_api/06_logging.ipynb` → `hwpapi/logging.py`

**Workflow for code changes:**
1. Read the relevant `.py` file to understand current implementation
2. Open corresponding `.ipynb` file in `nbs/`
3. Make changes in notebook cells
4. Run `nbdev_export` to regenerate `.py` files
5. Test changes

### Configuration Files

- `settings.ini` - Master nbdev configuration (version, metadata, paths)
- `pyproject.toml` - Build system (references settings.ini)
- `setup.py` - Dynamic setup from settings.ini

## Architecture and Design Patterns

### Core Class Hierarchy

```
App                        # High-level API for users
  └─ Engine                # Mid-level wrapper around HwpObject
       └─ HwpObject (COM)  # Raw win32com interface

Accessors:
  - MoveAccessor           # Cursor movement
  - CellAccessor           # Table cell operations
  - TableAccessor          # Table manipulation
  - PageAccessor           # Page operations
```
G'N m<>
Actions represent HWP operations (e.g., `InsertText`, `FindReplace`). ParameterSets configure action parameters.

**Two modes:**
1. **Pset-based** (preferred, modern): Immediate effect, no staging
2. **HSet-based** (legacy): Requires staging and `apply()` method

**Example:**
```python
# Pset-based (preferred)
app.insert_text("Hello", pset={"fontname": "Arial", "fontsize": 12})

# HSet-based (legacy, still supported)
hparam = app.create_set("InsertText")
hparam.fontname = "Arial"
app.insert_text("Hello", hset=hparam)
```

### Backend Abstraction

Multiple backend implementations handle different parameter set types:

- `PsetBackend` - For pset dicts (preferred)
- `HParamBackend` - For HParameterSet objects (legacy)
- `ComBackend` - For generic COM objects
- `AttrBackend` - For plain Python objects

Factory function `make_backend()` auto-detects appropriate backend.

### Property Descriptor System

Type-safe property descriptors provide validation and type conversion:

- `IntProperty`, `BoolProperty`, `StringProperty`
- `ColorProperty`, `UnitProperty`, `MappedProperty`
- `TypedProperty`, `ListProperty`

Metaclass `ParameterSetMeta` auto-generates `_attrs` list from property descriptors.

### Naming Conventions

- **Classes:** PascalCase (`App`, `Engine`, `CharShape`, `ParameterSet`)
- **Functions/Methods:** snake_case (`insert_text`, `get_charshape`, `move_to_end`)
- **Constants/Enums:** UPPER_CASE or PascalCase (`DIRECTION_MAP`, `FontType`)
- **Private classes:** Leading underscore (`_Action`, `_Actions`)
- **Module-level exports:** Use `__all__` explicitly

### Code Style

- Korean docstrings and comments for user-facing documentation
- English allowed for technical implementation details
- Chaining support: methods return `self` where appropriate
- Context managers for temporary state changes (e.g., `temp_edit_hparam`)

## Key Files and Modules

### Core Modules (in hwpapi/)

- `core.py` (1,936 lines) - `App` and `Engine` classes, core API
- `actions.py` (3,841 lines) - 899+ HWP action definitions
- `parametersets.py` (4,123 lines) - Parameter set classes with property descriptors
- `classes.py` (1,728 lines) - Helper classes (`CharShape`, `ParaShape`, accessors)
- `constants.py` (643 lines) - Enums and constant mappings
- `functions.py` (455 lines) - Utility functions
- `logging.py` (308 lines) - Centralized logging (`HwpApiLogger`)

### Source Notebooks (in nbs/)

- `index.ipynb` - Main documentation
- `01_tutorials/` - Tutorial notebooks for users
- `02_api/` - API documentation notebooks (source code)

### Tests

- `tests/test_hparam.py` - HParameterSet support tests using unittest
- Mock-based unit tests + integration tests (requires HWP)
- Graceful skipping when dependencies unavailable

## Dependencies

**Runtime:**
- `pywin32` - Windows COM interface to HWP
- `fastcore` - FastAI utilities

**Development:**
- `nbdev` - Notebook-driven development framework
- Quarto - Documentation generation

**Minimum Python:** 3.7+

## Common Tasks

### Adding a New Feature

1. Identify appropriate notebook in `nbs/02_api/`
2. Add feature in notebook cell (with tests/examples)
3. Export: `nbdev_export`
4. Test the generated code
5. Update documentation if needed

### Fixing a Bug

1. Read the `.py` file to understand the bug
2. Open corresponding `.ipynb` file
3. Fix the bug in notebook cell
4. Run `nbdev_export`
5. Run tests to verify fix

### Adding a New Action

1. Edit `nbs/02_api/01_actions.ipynb`
2. Add action definition to `_Actions` class
3. Create corresponding ParameterSet if needed in `02_parameters.ipynb`
4. Export: `nbdev_export`
5. Add tests and examples

### Refactoring

- Recent major refactoring migrated from HSet to pset-based approach
- See `PSET_MIGRATION_SUMMARY.md` and `REFACTORING_SUMMARY.md` for context
- Maintain backward compatibility with HSet-based code
- Prefer pset-based implementations for new code

## Testing Strategy

- Framework: unittest (Python standard library)
- Location: `tests/test_hparam.py`
- Coverage: Backend selection, parameter manipulation, integration tests
- Approach: Unit tests (mocks) + integration tests (real HWP)
- Skip tests gracefully when dependencies missing

## Build and Deploy

**Build:**
```bash
nbdev_export          # Generate .py files from notebooks
python setup.py sdist bdist_wheel
```

**Test:**
```bash
python -m pytest tests/
```

**Documentation:**
```bash
nbdev_docs            # Generate documentation
```

**Deploy:**
- GitHub Actions workflow (`.github/workflows/deploy.yaml`)
- Windows runner (HWP dependency)
- Auto-deploys to GitHub Pages on push to main

## Domain-Specific Knowledge

### HWP (Hancom Office)

- Korean word processor (similar to MS Word)
- COM automation via `HwpObject`
- Actions executed via `Run()` with parameter sets
- Complex object model: CharShape, ParaShape, BorderFill, etc.

### Win32com Interface

- Raw COM object access via `app.api`
- Type conversion needed (Python ↔ COM)
- Some operations return None, others return values
- Cursor-based editing model

## Recent Changes

Project underwent significant refactoring (see PSET_MIGRATION_SUMMARY.md):
- Migration from HSet-based to pset-based parameter handling
- Simplified ParameterSet implementation using property descriptors
- Backend abstraction for different parameter set types
- Improved type safety and validation
- Maintained backward compatibility

## Common Pitfalls

1. **Editing .py files directly** - Always edit notebooks instead
2. **Forgetting to run nbdev_export** - Changes in notebooks won't take effect
3. **Platform assumptions** - This is Windows-only code
4. **HWP availability** - Integration tests require HWP installed
5. **Staging confusion** - Pset-based is immediate, HSet-based requires apply()
6. **Type conversion** - COM interface has specific type requirements

## Code Examples

### Basic Usage
```python
from hwpapi import App

app = App()
app.open("document.hwp")
app.insert_text("Hello, World!")
app.save()
app.quit()
```

### Using Pset (Preferred)
```python
app.insert_text("Bold text", pset={"bold": True, "fontsize": 14})
```

### Using Accessors
```python
app.move.to_end()
app.cell[0, 0].text = "Cell content"
```

## Resources

- Documentation: Auto-generated from notebooks
- Examples: `examples/` directory
- Tutorials: `nbs/01_tutorials/`
- Migration guides: PSET_MIGRATION_SUMMARY.md, REFACTORING_SUMMARY.md

## Notes for AI Assistants

- Always check if editing a `.py` file before making changes - redirect to notebook
- Understand pset vs HSet distinction when working with parameters
- Respect bilingual nature - Korean for user docs, English for technical
- Recent refactoring means some patterns may be in transition
- When in doubt about architecture decisions, reference migration/refactoring docs
- Test changes carefully as this wraps a COM interface (side effects possible)