질문 남겨주셔서 감사합니다.

pyhwpx는 2023년 말에 진행했던 모 기관 연수원 강의에서

짧은 시간 동안 한/글 자동화 전반에 대해 알려드리기 위해 만들었던

한/글 오토메이션API의 래퍼 모듈입니다.

내부적으로는 오토메이션API를 활용하지만,

보다 간편한 명령어를 통해 직관적으로 한/글과 상호작용할 수 있습니다.

이 글에 모두 담을 수는 없지만,

설치 및 간단한 실행방법을 보여드리고,

차근차근 질문게시판이나 강의 부록 등을 통해 상세히 설명드리겠습니다.

1. 설치방법

pyhwpx는 pip를 통해 간편하게 설치하실 수 있습니다.

커맨드프롬프트(터미널)에서
(만약 가상환경을 사용하신다면, 활성화하신 상태에서)

pip install pyhwpx 명령어를 실행하시면 됩니다.

최근 기능추가나 여러 이슈 등으로 잦은 버전업을 하고 있으니,
틈틈이 pip install --upgrade pyhwpx 명령어를 통해 업데이트를 해 주시는 걸 추천드립니다.

2. 실행방법

pyhwpx의 Hwp 클래스를 임포트하신 후에
hwp = Hwp()명령어로 한/글을 실행하실 수 있습니다.

기존 강의에서 사용하는 win32의 hwp(이하 win32_hwp)와
pyhwpx의 hwp(이하 hwp)는 엄연히 다른 객체입니다. 착오 없으시기를 바랍니다.
다만 win32_hwp의 모든 메서드는 hwp를 통해 실행할 수 있습니다.
이 부분은 차근차근 설명드리겠습니다.

pyhwpx 내부적으로는
보안모듈 설치 및 실행, 기존에 열린 아래아한글 창을 찾아서 연결하는 등
초기에 실행하는 코드 대부분을 인스턴스화 시점에 자동으로 처리하므로
레지스트리에디터 등록이나 RegisterModule 메서드를 별도로 실행하지 않으셔도 됩니다.

3. 표 만들기

표를 생성하는 메서드는 create_table입니다.
아래 명령어는 5행5열의 표를 '글자처럼 취급'으로 생성합니다.
hwp.create_table(5, 5, treat_as_char=True)

4. 기존 오토메이션API의 명령어를 실행하려면

기존 win32_hwp에서 사용했던 메서드와 속성은
hwp.hwp를 통해서도 실행하실 수 있지만, (hwp.hwp == win32_hwp)
대부분은 hwp 안에서도 아래 방법으로 사용하실 수 있습니다.

4-1. 기존의 Run("ActionID") 메서드는

기존에 win32_hwp.Run(액션아이디) 또는 win32_hwp.HAction.Run(액션아이디)로 실행했던 액션은
hwp에서는 액션아이디 그대로 메서드로 사용하실 수 있습니다.

예를 들어 win32_hwp.Run("SelectAll") 은 hwp.SelectAll() 방식으로 실행합니다.

아래 코드는 5행5열의 표 안에 0부터 24까지 차례대로 채우는 코드입니다.
기존의 Run 메서드가 어떻게 바뀌었는지 살펴보시기 바랍니다.

for i in range(25):
    hwp.insert_text(i)
    hwp.TableRightCell()  # 기존: hwp.HAction.Run("TableRightCell")

4-2. win32_hwp 의 다양한 속성들(HAction, HParameter 등)

그밖에도 컨트롤을 탐색하기 위해 사용했던 win32_hwp의 HeadCtrl, LastCtrl,
액션 관련한 HParameterSet, HAction,
한/글 프로그램이나 창을 제어하기 위한 XHwpDocuments, XHwpWindows 등 모두
기존과 동일하게 사용 가능합니다.

현재 hwp 인스턴스 안에서
직접 호출 가능한 win32_hwp의 속성은 아래의 30개입니다.

Application
CellShape
CharShape
CLSID
coclass_clsid
CurFieldState
CurMetatagState
CurSelectedCtrl
EditMode
EngineProperties
HAction
HeadCtrl
HParameterSet
IsEmpty
IsModified
IsPrivateInfoProtected
IsTrackChangePassword
IsTrackChange
LastCtrl
PageCount
ParaShape
ParentCtrl
Path
SelectionMode
Version
ViewProperties
XHwpDocuments
XHwpMessageBox
XHwpODBC
XHwpWindows

4-3. 기존 메서드의 보완

win32_hwp의 기존 메서드 중에서도 다소 사용법이 불편했던 메서드는 일부 보완중입니다.

예를 들어,

hwp.open() 메서드나 hwp.save_as() 메서드 등은 상대경로로 입력 가능합니다.
hwp.insert_picture() 메서드 사용시 이미지 너비나 높이가 페이지를 넘는 경우 자동으로 페이지에 들어오게끔 리사이즈를 합니다. 셀 안에 들어있을 때에는 셀 너비에 맞게 리사이징합니다.
hwp.insert_picture() 메서드에 온사인상의 이미지URL을 입력할 수 있습니다.
hwp.clear() 메서드 입력시 자동으로 "변경사항 버림"액션을 선행합니다.
팝업이 뜨기 십상인 hwp.TableMergeTable()이나 hwp.Cut() 액션 등은 내부적으로 SetMessageBoxMode를 잠깐 활성화하여 팝업이 뜨지 않게 처리합니다.
그 외에 기존의 win32_hwp에서 파스칼 케이스(PascalCase) 로 실행하는 메서드는 대부분 소문자단어 사이에 언더스코어가 붙은 스네이크케이스(snake_case)로 실행하실 수 있습니다. 예를 들어, win32_hwp.PutFieldText는 hwp.put_field_text로, win32_hwp.Open은 hwp.open으로 사용하실 수 있습니다.
put_field_text 메서드는 dict, list, tuple 및 pandas.Series, DataFrame 등 다양한 자료형을 받을 수 있습니다. 이 경우, dict의 키[또는 2중리스트의 0번 인덱스 문자열, 데이터프레임의 칼럼명, 시리즈의 인덱스 등]을 문서상의 필드명(누름틀/셀필드)과 대조하여 일치하는 필드끼리 자동으로 매치해줍니다.

(참고 포스팅 : pyhwpx로 필드 채우는 방법 기초(중요) (tistory.com))

5. pyhwpx의 오리지널 메서드

win32_hwp에서 자주 쓰이던 패턴들을 pyhwpx 고유의 메서드로 추가했습니다.
제법 많기도 하고, 지금도 계속 추가하고 있는 중입니다.
우선 유용한 메서드 10개만 소개해드립니다.

1. table_to_df(표를 데이터프레임으로 내보내기)

2. table_from_data(dict, list, 데이터프레임이나 엑셀, csv파일 등을 한/글의 표로 만들기)

3. fields_to_dict(문서의 필드명과 값을 dict로 변환하기)

4. get_into_nth_table(문서의 n번째 표로 들어가기)

5. get_pagedef_as_dict(페이지설정을 딕셔너리로 추출)

6. set_pagedef(위에서 추출하여 수정한 딕셔너리 값으로 페이지 설정)

7. delete_all_fields(값은 남겨두고 필드는 전부 제거)

8. clear_field_text(필드는 남겨두고 필드의 값을 전부 제거)

9. find_replace_all(찾아바꾸기, 파이썬 문법의 정규식 찾아바꾸기 가능)

10. get_selected_text(선택한 문자열 또는, 선택한 셀의 값을 파이썬으로 가져오기)

등입니다. 이밖에도 create_table이나 insert_memo, open_pdf 등
소개해드리고 싶은 메서드가 참 많습니다.

앞으로 틈틈이 강의와 QnA를 통해서
사용법과 사례를 자세히 알려드리겠습니다.

도움이 되길 바랍니다.
행복한 하루 되세요^^

일코 드림

인프런 커뮤니티 질문&답변

pyhwpx 사용법도 알려주세요!