디버깅 도구

뭔가 잘못됐을 때, 어디를 봐야 하는가

nbs/01_tutorials/13_debugging_tools.ipynb 에서 이식.

1. 디버그 로깅 켜기

import os
os.environ["HWPAPI_LOG_LEVEL"] = "DEBUG"

from hwpapi import App
# 이제 모든 COM 호출과 인자가 로그에 출력됨

기본 레벨은 WARNING 입니다 — 정상 동작하는 스크립트는 로그 출력이 없습니다. DEBUG 는 수다스럽고, INFO 가 일반적인 dev-mode 중간 지점입니다.

2. 액션 실행 없이 들여다보기

from hwpapi import App

with App() as app:
    cls = app.actions.get_pset_class("FindReplace")
    desc = app.actions.get_description("FindReplace")
    print(desc)
    print("properties:", list(cls._property_registry.keys())[:10])

3. ParameterSet 출력

__repr__ 는 사람이 읽기 좋은 값과 인라인 doc 코멘트를 렌더링합니다.

from hwpapi import App

with App() as app:
    ps = app.actions.CharShape.pset
    ps.Bold = True
    ps.Height = 1400
    ps.TextColor = "#FF0000"
    print(ps)
    # CharShape(
    #   Bold=True  # Bold formatting
    #   Height=14.0pt  # Font size in HWPUNIT (100=1pt)
    #   TextColor="#ff0000"  # Text color in BBGGRR format
    # )

4. raw COM 레이어로 탈출

from hwpapi import App

with App() as app:
    # Raw HWP COM 핸들 — 자동화 SDK 가 노출하는 모든 것
    hwp = app.api

    print("Document count:", hwp.XHwpDocuments.Count)
    print("Active format:", hwp.Version)

5. raw COM 에러를 잡기 위한 `FailableCOMCall` 사용

대부분의 퍼사드 호출은 hwpapi.errors.HwpApiError 의 서브클래스를 발생시키지만, app.api 로 내려가면 raw pywintypes 가 나옵니다.

from hwpapi import App
from hwpapi.errors import ActionFailedError, wrap_com_error

with App() as app:
    with wrap_com_error(action_name="Save"):
        app.api.Save()
    # raw com_error 는 이제 ActionFailedError 로 다시 발생됨

6. pset 스냅샷 / 차이

ps = app.actions.CharShape.pset
before = ps.clone()

ps.Bold = True
ps.Italic = True

after = ps.clone()
print("equivalent?", before.is_equivalent(after))  # False
print("changes:", {
    k: (getattr(before, k, None), getattr(after, k, None))
    for k in before._property_registry
    if getattr(before, k, None) != getattr(after, k, None)
})

7. public 표면 전체 덤프

import hwpapi
public = sorted(n for n in dir(hwpapi) if not n.startswith("_"))
print(public)

['App', 'Document', 'annotations', 'constants', 'core', 'document', 'functions', 'logging', 'low']

함께 보기

Reference: errors — 예외 계층
Reference: low.actions — 액션 인트로스펙션 표면

맨 위로