Low-level escape hatch

hwpapi.low.actions / parametersets / engine

두 계층 규칙

hwpapi 는 두 개의 적층 API 로 설계되어 있습니다.

  1. High-level (hwpapi.App → app.doc.*) — 95% 의 사용자가 작성해야 하는 것. 컬렉션, element, context scope, units. 각 작업에 대해 하나의 방법.
  2. Low-level (hwpapi.low.*) — raw HWP 액션 wrapper 와 ParameterSet 클래스. deprecated 가 아닙니다 — 공식적으로 지원되는 escape hatch 입니다. high-level API 가 필요한 것을 노출하지 않을 때 사용하세요.

경계 정책 (ADR-001 에서):

“high 계층이 적극적으로 차단하는 기능이 hwpapi.low 에서만 제공된다면 그것은 버그입니다. 그 역도 버그입니다. hwpapi.low 는 항상 자급자족적이며, high 계층은 항상 hwpapi.low 의 표현으로 표현 가능합니다.”

hwpapi.low 를 사용한다고 해서 “위험한 것으로 떨어지는” 것이 아닙니다. 본인(그리고 다른 누구도 모르는) 만의 이유로 다른 추상화 수준을 사용하는 것입니다.

세 개의 서브모듈

from hwpapi.low import actions       # 900+ 액션 wrapper
from hwpapi.low import parametersets # 130+ ParameterSet 클래스
from hwpapi.low import engine        # Engine / Engines / Apps

hwpapi.low.actions

HWP 의 약 900개 명명된 액션 (InsertText, CharShape, FileOpen, …) 각각을 Python 친화적 callable 로 감쌉니다. 모든 wrapper 는:

  • .pset 노출 — 액션에 바인딩된 ParameterSet
  • .run() 노출 — pset 으로 HAction.Execute() 호출
  • .description 노출 — HWP 액션 카탈로그의 한국어 설명 문자열
from hwpapi.low import actions

charshape = actions._Action("CharShape")

# 타입 안전한 프로퍼티 접근
charshape.pset.Bold = True
charshape.pset.Height = 1400       # 14pt (HWPUNIT: 100/pt)
charshape.pset.TextColor = "#FF0000"

charshape.run()

또는 app 의 사전 빌드된 카탈로그를 통해서도.

from hwpapi import App

app = App()
charshape = app.actions.CharShape   # 같은 인스턴스
charshape.pset.Italic = True
charshape.run()

app.actions.list_actions() 는 등록된 모든 이름을 반환합니다. app.actions.get_pset_class("CharShape") 는 COM 을 건드리지 않고 ParameterSet 클래스 를 반환합니다 (introspection 에 유용).

hwpapi.low.parametersets

HWP 의 HParameterSet COM 객체에 대한 타입 안전한 Python wrapper 입니다. 각 ParameterSet 클래스는:

  • 클래스 레벨 PropertyDescriptor 로 프로퍼티를 선언 (IntProperty, BoolProperty, ColorProperty, UnitProperty, MappedProperty, NestedProperty, ArrayProperty)
  • __repr__ 을 통해 사람이 읽을 수 있는 값으로 자기 자신을 렌더링 (1200 HWPUNIT 대신 12pt, 0x0000FF 대신 #ff0000)
  • .clone() (스냅샷), .update_from(other) (복원), .is_equivalent(other) (비교) 지원
from hwpapi.low.parametersets import CharShape

cs = CharShape()
cs.Bold = True
cs.Height = 1400
cs.TextColor = "#FF0000"
print(cs)
# CharShape(
#   Bold=True  # 굵게 서식
#   Height=14.0pt  # HWPUNIT 글꼴 크기 (100=1pt)
#   TextColor="#ff0000"  # BBGGRR 형식의 텍스트 색상
# )

전체 카탈로그는 Reference: low.parametersets 페이지를 참고하세요.

hwpapi.low.engine

  • Engine — HWP COM 엔진 하나를 감쌉니다. engine.impl 이 raw COM 핸들 (HwpObject) 입니다.
  • Engines — 활성 엔진의 레지스트리.
  • Apps — App facade 의 병렬 레지스트리.

이들을 직접 생성하는 일은 거의 없습니다. App() 이 사용자를 위해 Engine 을 만듭니다. hwpapi 가 감싸지 않은 raw COM 메서드를 호출해야 할 때 app.engine 을 통해 접근합니다.

from hwpapi import App

with App() as app:
    # hwpapi 가 감싸지 않은 raw COM 호출
    app.engine.impl.XHwpDocuments.Item(0).Save()

    # 또는 더 raw 한 단축
    app.api.XHwpDocuments.Count

언제 내려갈 것인가

먼저 high-level facade 를 사용하세요. 다음의 경우 hwpapi.low 로 내려가세요.

  • high-level API 가 노출하지 않는 특정 ParameterSet 프로퍼티가 필요할 때 (FindReplace 의 중첩된 shape 에서 흔함).
  • high-level API 가 감싸지 않은 액션을 호출해야 할 때.
  • 아무것도 실행하지 않고 introspection (app.actions.list_actions()) 만 하고 싶을 때.
  • hwpapi 위에 자신만의 추상화를 빌드하면서 facade 가 제공할 수 없는 안정성 보장을 원할 때.

일반 사용자 영역처럼 보이는 것을 위해 hwpapi.low 에 들어가게 된다면 — 그것은 facade 의 빈틈입니다. 이슈를 열어 주세요.

삭제된 것

low 계층으로 요청을 간접적으로 라우팅하던 v1 이름 몇 개가 제거되었습니다.

v1 v2
app.actions 여전히 존재 (App 의 escape hatch) 또는 hwpapi.low.actions
app.create_action(n) hwpapi.low.actions._Action(n)
app.create_parameterset(...) hwpapi.low.parametersets 클래스 생성자
app.parameters hwpapi.low.parametersets

마이그레이션 가이드 를 참고하세요.

더 보기

맨 위로