hangeul

파이썬용 한글 텍스트 처리 도구 모음입니다.

English summary. hangeul is a small, dependency-free Python library for Korean (Hangul) text. It splits syllables into jamo and assembles jamo back into syllables (including double final consonants and liaison, e.g. ㄱㅏㅂㅅㅇㅣ -> 값이), picks the right particle (josa) after a word, including numbers and uppercase acronyms (IBM이, SDK는, 7로), supports initial-consonant (choseong) search, measures jamo-level string similarity, and reads numbers aloud in Korean (1234 -> 천이백삼십사). Python 3.10+.

설치

pip install hangeul
# 또는
uv add hangeul

빠른 시작

import hangeul as han

# 조사 선택 (숫자, 영문 대문자 약어, 괄호 처리)
print(han.attach("IBM", "이/가"))           # IBM이
print(han.attach("SDK", "은/는"))           # SDK는
print(han.attach("7", "으로/로"))           # 7로
print(han.attach("애플(Apple)", "이/가"))   # 애플(Apple)이

# 자모 분해와 조합
print(han.disassemble("값이"))              # ㄱㅏㅂㅅㅇㅣ
print(han.assemble("ㄱㅏㅂㅅㅇㅣ"))        # 값이

# 초성 검색
print(han.matches("서강대학교", "ㅅㄱㄷ"))  # True
print(han.search_filter(["사과", "수박", "포도"], "ㅅㅂ"))  # ['수박']

# 자소 단위 유사도 (0.0 ~ 1.0)
print(han.similarity("값", "갑"))           # 0.75

# 숫자 읽기
print(han.num2han(1234567))                 # 백이십삼만사천오백육십칠

API

조사

지원 패턴: 이/가, 은/는, 을/를, 와/과, 아/야, 나/이나, 란/이란, 랑/이랑, 라/이라, 예요/이에요, 로/으로, 로서/으로서, 로써/으로써, 로부터/으로부터. 로 계열은 ㄹ 받침 뒤에서 로를 고릅니다. 그 밖의 두 항목 패턴은 받침 있을 때/받침 없을 때 순서로 해석합니다. 마지막 글자가 숫자이면 한국어 읽기(일, 이, 삼...)로, 영문 대문자 약어이면 알파벳 이름(에이, 비, 씨...)으로 판단합니다. 소문자 영단어는 받침 없음으로 취급하며, 끝의 괄호 부분은 무시합니다.

조합과 분해

검색과 유사도

문자 판별

숫자

상수

CHOSOENG, JUNGSOENG, JONGSOENG: 유니코드 음절 순서대로 정렬된 초성(19), 중성(21), 종성(28, 첫 항목은 빈 문자열) 튜플.

개발

uv run pytest
uv run ruff check .

라이선스

MIT