hangeul 0.1.0__tar.gz

hangeul-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hangeul
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pytest>=9.0.3
+
+# hangeul
+
+파이썬 환경에서 한글을 다루기 위한 현대적인 툴킷입니다. 
+
+기존의 파이썬용 한글 라이브러리들은 최신 개발 환경(Type Hinting, Python 3.10+ 등)에 최적화되어 있지 않거나 기능이 파편화되어 있었습니다. hangeul은 조합/분해 오토마타를 기반으로 실무에서 즉시 사용 가능한 강력한 기능들을 통합하여 제공합니다.
+
+---
+
+## 핵심 강점
+
+* **조사(Josa) 처리**: 단순히 받침 유무만 체크하지 않고 영문 약어(SDK, IBM 등)의 발음과 숫자(7, 8 등)의 종성 발음을 인식하여 조사를 선택합니다.
+* **자소 단위 유사도 매칭**: 단어 단위가 아닌 초/중/종성 단위의 편집 거리(Levenshtein Distance)를 계산하여 오타 교정에 최적화된 유사도 점수를 제공합니다.
+* **오토마타 기반 조합/분해**: 연음 법칙을 고려한 조합 로직을 통해 `ㄱㅏㅂㅅㅇㅣ`를 `값이`로 정확히 조립합니다. 
+* **Zero Dependency**: 외부 라이브러리 의존성 없이 파이썬 표준 라이브러리만으로 동작합니다.
+* **Modern Development**: 전 기능에 대한 타입 힌팅을 지원하며, `uv` 및 최신 파이썬 환경에 최적화되어 있습니다.
+
+---
+
+## 주요 기능 및 예제
+
+### 1. 조사(Josa) 결합
+단순 문자열 비교가 아닌 발음 기반의 처리를 수행합니다.
+
+```python
+import hangeul
+
+# 영문 약어 발음 인식
+hangeul.attach("SDK", "은/는")  # "SDK는" (에스디케이 - 받침 없음)
+hangeul.attach("IBM", "이/가")  # "IBM이" (아이비엠 - ㅁ받침)
+
+# 숫자 종성 인식
+hangeul.attach("7", "으로/로")  # "7로" (칠 - ㄹ받침 예외)
+hangeul.attach("10", "을/를")  # "10을" (십 - ㅂ받침)
+
+# 괄호 제거 후 판별
+hangeul.attach("애플(Apple)", "이/가")  # "애플(Apple)이"
+```
+
+### 2. 조합 및 분해 (Assemble / Disassemble)
+한국어 음운 규칙을 따르는 조립과 완전 분해를 지원합니다.
+
+```python
+# 조합 (연음 법칙 적용)
+hangeul.assemble("ㄱㅏㅂㅅㅇㅣ")  # "값이"
+
+# 분해 (겹받침/복합모음 완전 분리)
+hangeul.disassemble("값")  # "ㄱㅏㅂㅅ"
+hangeul.disassemble("과")  # "ㄱㅗㅏ"
+```
+
+### 3. 유사도 분석 및 검색
+오타에 강한 검색 기능을 구현할 때 유용합니다.
+
+```python
+# 자소 단위 유사도 (0.0 ~ 1.0)
+# '값'과 '갑'은 글자 단위에선 0점이지만 자소 단위에선 0.75점입니다.
+hangeul.jamo_similarity("값", "갑")  # 0.75
+
+# 초성 검색 및 부분 일치
+hangeul.matches("서강대학교", "ㅅㄱㄷ")  # True
+hangeul.matches("한글", "ㅎㅏㄴ")  # True
+```
+
+### 4. 숫자 한글 변환
+숫자 단위를 분석하여 관습적인 한글 읽기 방식으로 변환합니다.
+
+```python
+hangeul.num2han(1234567)  # "백이십삼만사천오백육십칠"
+hangeul.num2han(10000)    # "만" (일만 -> 만 축약 적용)
+```
+
+---
+
+## 설치
+
+```bash
+pip install hangeul
+# or
+uv add hangeul
+```
+
+## 환경
+* Python 3.10 이상 권장
+* 의존성 없음 (Standard Library Only)
+
+## 기여 및 문의
+버그 리포트나 기능 제안은 이슈 트래커를 이용해 주세요. High Cohesion, Low Coupling 원칙을 준수하며 관리됩니다.

hangeul-0.1.0/README.md

@@ -0,0 +1,87 @@
+# hangeul
+
+파이썬 환경에서 한글을 다루기 위한 현대적인 툴킷입니다. 
+
+기존의 파이썬용 한글 라이브러리들은 최신 개발 환경(Type Hinting, Python 3.10+ 등)에 최적화되어 있지 않거나 기능이 파편화되어 있었습니다. hangeul은 조합/분해 오토마타를 기반으로 실무에서 즉시 사용 가능한 강력한 기능들을 통합하여 제공합니다.
+
+---
+
+## 핵심 강점
+
+* **조사(Josa) 처리**: 단순히 받침 유무만 체크하지 않고 영문 약어(SDK, IBM 등)의 발음과 숫자(7, 8 등)의 종성 발음을 인식하여 조사를 선택합니다.
+* **자소 단위 유사도 매칭**: 단어 단위가 아닌 초/중/종성 단위의 편집 거리(Levenshtein Distance)를 계산하여 오타 교정에 최적화된 유사도 점수를 제공합니다.
+* **오토마타 기반 조합/분해**: 연음 법칙을 고려한 조합 로직을 통해 `ㄱㅏㅂㅅㅇㅣ`를 `값이`로 정확히 조립합니다. 
+* **Zero Dependency**: 외부 라이브러리 의존성 없이 파이썬 표준 라이브러리만으로 동작합니다.
+* **Modern Development**: 전 기능에 대한 타입 힌팅을 지원하며, `uv` 및 최신 파이썬 환경에 최적화되어 있습니다.
+
+---
+
+## 주요 기능 및 예제
+
+### 1. 조사(Josa) 결합
+단순 문자열 비교가 아닌 발음 기반의 처리를 수행합니다.
+
+```python
+import hangeul
+
+# 영문 약어 발음 인식
+hangeul.attach("SDK", "은/는")  # "SDK는" (에스디케이 - 받침 없음)
+hangeul.attach("IBM", "이/가")  # "IBM이" (아이비엠 - ㅁ받침)
+
+# 숫자 종성 인식
+hangeul.attach("7", "으로/로")  # "7로" (칠 - ㄹ받침 예외)
+hangeul.attach("10", "을/를")  # "10을" (십 - ㅂ받침)
+
+# 괄호 제거 후 판별
+hangeul.attach("애플(Apple)", "이/가")  # "애플(Apple)이"
+```
+
+### 2. 조합 및 분해 (Assemble / Disassemble)
+한국어 음운 규칙을 따르는 조립과 완전 분해를 지원합니다.
+
+```python
+# 조합 (연음 법칙 적용)
+hangeul.assemble("ㄱㅏㅂㅅㅇㅣ")  # "값이"
+
+# 분해 (겹받침/복합모음 완전 분리)
+hangeul.disassemble("값")  # "ㄱㅏㅂㅅ"
+hangeul.disassemble("과")  # "ㄱㅗㅏ"
+```
+
+### 3. 유사도 분석 및 검색
+오타에 강한 검색 기능을 구현할 때 유용합니다.
+
+```python
+# 자소 단위 유사도 (0.0 ~ 1.0)
+# '값'과 '갑'은 글자 단위에선 0점이지만 자소 단위에선 0.75점입니다.
+hangeul.jamo_similarity("값", "갑")  # 0.75
+
+# 초성 검색 및 부분 일치
+hangeul.matches("서강대학교", "ㅅㄱㄷ")  # True
+hangeul.matches("한글", "ㅎㅏㄴ")  # True
+```
+
+### 4. 숫자 한글 변환
+숫자 단위를 분석하여 관습적인 한글 읽기 방식으로 변환합니다.
+
+```python
+hangeul.num2han(1234567)  # "백이십삼만사천오백육십칠"
+hangeul.num2han(10000)    # "만" (일만 -> 만 축약 적용)
+```
+
+---
+
+## 설치
+
+```bash
+pip install hangeul
+# or
+uv add hangeul
+```
+
+## 환경
+* Python 3.10 이상 권장
+* 의존성 없음 (Standard Library Only)
+
+## 기여 및 문의
+버그 리포트나 기능 제안은 이슈 트래커를 이용해 주세요. High Cohesion, Low Coupling 원칙을 준수하며 관리됩니다.

hangeul-0.1.0/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "hangeul"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pytest>=9.0.3",
+]

hangeul-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hangeul-0.1.0/src/hangeul/__init__.py

@@ -0,0 +1,68 @@
+__version__ = "0.1.0"
+
+from .check import (
+    is_han,
+    is_pure_han,
+    has_batchim,
+    can_cho,
+    can_jung,
+    can_jong,
+)
+from .core import (
+    assemble,
+    disassemble,
+    qwerty2han,
+)
+from .josa import (
+    get_josa,
+    attach,
+)
+from .search import (
+    matches,
+    get_chosung,
+    search_filter,
+)
+from .constants import (
+    CHOSOENG,
+    JUNGSOENG,
+    JONGSOENG,
+)
+from .similarity import jamo_similarity
+from .number import num2han
+
+
+__all__: list[str] = [
+    # Metadata
+    "__version__",
+    
+    # Check API
+    "is_han",
+    "is_pure_han",
+    "has_batchim",
+    "can_cho",
+    "can_jung",
+    "can_jong",
+    
+    # Core API
+    "assemble",
+    "disassemble",
+    "qwerty2han",
+    
+    # Josa API
+    "get_josa",
+    "josa",
+    "attach",
+    
+    # Search API
+    "matches",
+    "get_chosung",
+    "search_filter",
+    
+    # Constants
+    "CHOSOENG",
+    "JUNGSOENG",
+    "JONGSOENG",
+
+    "jamo_similarity",
+    "num2han"
+]

hangeul-0.1.0/src/hangeul/check.py

@@ -0,0 +1,53 @@
+import unicodedata
+from typing import Literal
+
+from .constants import 초성, 중성, 종성
+
+_NormalizationForm = Literal[
+    "NFC", "NFD", "NFKC", "NFKD",
+    "nfc", "nfd", "nfkc", "nfkd"
+]
+
+def normalize(text: str, form: _NormalizationForm = "NFC") -> str:
+    """
+    텍스트를 유니코드 정규화 형식으로 변환합니다.
+    기본값은 NFC(완성형)이며, macOS 환경과의 호환성을 위해 사용합니다.
+    """
+    return unicodedata.normalize(form.upper(), text)
+
+def is_han(text: str, allow_space: bool = True, allow_punctuation: bool = False) -> bool:    
+    if not isinstance(text, str) or not text:
+        return False
+
+    for char in text:
+        if ('가' <= char <= '힣' or 'ㄱ' <= char <= 'ㅣ'):
+            continue
+        if allow_space and char.isspace():
+            continue
+        if allow_punctuation and unicodedata.category(char).startswith('P'):
+            continue
+
+        return False
+        
+    return True
+
+def is_pure_han(text: str) -> bool:
+    if not text:
+        return False
+
+    return all('가' <= c <= '힣' or 'ㄱ' <= c <= 'ㅣ' for c in text)
+
+def can_cho(char: str) -> bool:
+    return char in 초성
+
+def can_jung(char: str) -> bool:
+    return char in 중성
+
+def can_jong(char: str) -> bool:
+    return char in 종성
+
+def has_batchim(char: str) -> bool:
+    if len(char) != 1 or not ('가' <= char <= '힣'):
+        return False
+    return (ord(char) - 0xAC00) % 28 > 0
+

hangeul-0.1.0/src/hangeul/constants.py

@@ -0,0 +1,62 @@
+from typing import Final
+from types import MappingProxyType
+
+
+초성: Final[tuple[str, ...]] = (
+    'ㄱ', 'ㄲ', 'ㄴ', 'ㄷ', 'ㄸ', 'ㄹ', 'ㅁ',
+    'ㅂ', 'ㅃ', 'ㅅ', 'ㅆ', 'ㅇ', 'ㅈ', 'ㅉ',
+    'ㅊ', 'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ',
+)
+
+중성: Final[tuple[str, ...]] = (
+    'ㅏ', 'ㅐ', 'ㅑ', 'ㅒ', 'ㅓ', 'ㅔ', 'ㅕ', 'ㅖ',
+    'ㅗ', 'ㅘ', 'ㅙ', 'ㅚ', 'ㅛ', 'ㅜ', 'ㅝ', 'ㅞ',
+    'ㅟ', 'ㅠ', 'ㅡ', 'ㅢ', 'ㅣ'
+)
+
+종성: Final[tuple[str, ...]] = (
+    '', 'ㄱ', 'ㄲ', 'ㄳ', 'ㄴ', 'ㄵ', 'ㄶ', 'ㄷ',
+    'ㄹ', 'ㄺ', 'ㄻ', 'ㄼ', 'ㄽ', 'ㄾ', 'ㄿ', 'ㅀ',
+    'ㅁ', 'ㅂ', 'ㅄ', 'ㅅ', 'ㅆ', 'ㅇ', 'ㅈ', 'ㅊ',
+    'ㅋ', 'ㅌ', 'ㅍ', 'ㅎ'
+)
+
+겹받침맵: MappingProxyType[tuple[str, str], str] = MappingProxyType({
+    ('ㄱ', 'ㅅ'): 'ㄳ', ('ㄴ', 'ㅈ'): 'ㄵ', ('ㄴ', 'ㅎ'): 'ㄶ', ('ㄹ', 'ㄱ'): 'ㄺ',
+    ('ㄹ', 'ㅁ'): 'ㄻ', ('ㄹ', 'ㅂ'): 'ㄼ', ('ㄹ', 'ㅅ'): 'ㄽ', ('ㄹ', 'ㅌ'): 'ㄾ',
+    ('ㄹ', 'ㅍ'): 'ㄿ', ('ㄹ', 'ㅎ'): 'ㅀ', ('ㅂ', 'ㅅ'): 'ㅄ'
+})
+
+복합모음맵: MappingProxyType[tuple[str, str], str] = MappingProxyType({
+    ('ㅗ', 'ㅏ'): 'ㅘ', ('ㅗ', 'ㅐ'): 'ㅙ', ('ㅗ', 'ㅣ'): 'ㅚ',
+    ('ㅜ', 'ㅓ'): 'ㅝ', ('ㅜ', 'ㅔ'): 'ㅞ', ('ㅜ', 'ㅣ'): 'ㅟ', ('ㅡ', 'ㅣ'): 'ㅢ'
+})
+
+쿼티한글맵: MappingProxyType[str, str] = MappingProxyType({
+    'q': 'ㅂ', 'w': 'ㅈ', 'e': 'ㄷ', 'r': 'ㄱ', 't': 'ㅅ',
+    'a': 'ㅁ', 's': 'ㄴ', 'd': 'ㅇ', 'f': 'ㄹ', 'g': 'ㅎ',
+    'z': 'ㅋ', 'x': 'ㅌ', 'c': 'ㅊ', 'v': 'ㅍ',
+    
+    'y': 'ㅛ', 'u': 'ㅕ', 'i': 'ㅑ', 'o': 'ㅐ', 'p': 'ㅔ',
+    'h': 'ㅗ', 'j': 'ㅓ', 'k': 'ㅏ', 'l': 'ㅣ',
+    'b': 'ㅠ', 'n': 'ㅜ', 'm': 'ㅡ',
+
+    'Q': 'ㅃ', 'W': 'ㅉ', 'E': 'ㄸ', 'R': 'ㄲ', 'T': 'ㅆ',
+    'O': 'ㅒ', 'P': 'ㅖ'
+})
+
+CHOSOENG: Final[tuple[str, ...]] = 초성
+JUNGSOENG: Final[tuple[str, ...]] = 중성
+JONGSOENG: Final[tuple[str, ...]] = 종성
+DOUBLE_JONG_MAP: MappingProxyType[tuple[str, str], str] = 겹받침맵
+COMPOUND_JUNG_MAP: MappingProxyType[tuple[str, str], str] = 복합모음맵
+QWERTY_HANGEUL_MAP: MappingProxyType[str, str] = 쿼티한글맵
+
+__all__: list[str]  = [
+    "CHOSOENG",
+    "JUNGSOENGS",
+    "JONGSOENGS",
+    "DOUBLE_JONG_MAP",
+    "COMPOUND_JUNG_MAP",
+    "QWERTY_HANGEUL_MAP"
+]

hangeul-0.1.0/src/hangeul/core.py

@@ -0,0 +1,160 @@
+from .constants import (
+    초성, 중성, 종성,
+    겹받침맵, 복합모음맵, 쿼티한글맵
+)
+
+# 성능을 위한 인덱스 맵 미리 생성 (O(1) lookup)
+_CHO_IDX = {char: i for i, char in enumerate(초성)}
+_JUNG_IDX = {char: i for i, char in enumerate(중성)}
+_JONG_IDX = {char: i for i, char in enumerate(종성)}
+_SPLIT_JONG_MAP = {v: k for k, v in 겹받침맵.items()}
+_SPLIT_JUNG_MAP = {v: k for k, v in 복합모음맵.items()}
+
+def qwerty2han(text: str) -> str:
+    """영문 쿼티 문자열을 한글 자모 문자열로 변환합니다."""
+    return "".join(쿼티한글맵.get(char, char) for char in text)
+
+def assemble(text: str) -> str:
+    """자소 단위로 분리된 문자열을 완성형 한글로 조합합니다."""
+    cho_idx, jung_idx, jong_idx = -1, -1, 0
+    result: list[str] = []
+
+    def make_syllable(c, r, t):
+        return chr(0xAC00 + (c * 21 * 28) + (r * 28) + t)
+
+    def flush():
+        nonlocal cho_idx, jung_idx, jong_idx
+        if cho_idx != -1 and jung_idx != -1:
+            result.append(make_syllable(cho_idx, jung_idx, jong_idx))
+        elif cho_idx != -1:
+            result.append(초성[cho_idx])
+        elif jung_idx != -1:
+            result.append(중성[jung_idx])
+        cho_idx, jung_idx, jong_idx = -1, -1, 0
+
+    for char in text:
+        # 1. 자음 처리
+        if char in _CHO_IDX or char in _JONG_IDX:
+            if cho_idx != -1 and jung_idx != -1:
+                if jong_idx == 0:  # 현재 받침 없음
+                    if char in _JONG_IDX:
+                        jong_idx = _JONG_IDX[char]
+                    else:  # 종성 불가 자음 (ㄸ, ㅃ, ㅉ)
+                        flush()
+                        cho_idx = _CHO_IDX.get(char, -1)
+                else:  # 현재 받침 있음 -> 겹받침 가능성 확인
+                    cur_jong = 종성[jong_idx]
+                    if (cur_jong, char) in 겹받침맵:
+                        jong_idx = _JONG_IDX[겹받침맵[(cur_jong, char)]]
+                    else:  # 겹받침 불가 -> 새 글자로
+                        flush()
+                        if char in _CHO_IDX:
+                            cho_idx = _CHO_IDX[char]
+                        else:
+                            result.append(char)
+            else:  # 초성만 있거나 새로 시작
+                if cho_idx != -1: flush()
+                if char in _CHO_IDX:
+                    cho_idx = _CHO_IDX[char]
+                else:
+                    result.append(char)
+
+        # 2. 모음 처리
+        elif char in _JUNG_IDX:
+            # 받침이 있는 상태에서 모음이 오면 연음 처리 (예: 값이 -> 갑시)
+            if jong_idx != 0:
+                cur_jong_char = 종성[jong_idx]
+                if cur_jong_char in _SPLIT_JONG_MAP:  # 겹받침인 경우 분리
+                    f_jong, s_cho = _SPLIT_JONG_MAP[cur_jong_char]
+                    result.append(make_syllable(cho_idx, jung_idx, _JONG_IDX[f_jong]))
+                    cho_idx, jung_idx, jong_idx = _CHO_IDX[s_cho], _JUNG_IDX[char], 0
+                else:  # 일반 받침은 다음 초성으로 이동
+                    result.append(make_syllable(cho_idx, jung_idx, 0))
+                    cho_idx, jung_idx, jong_idx = _CHO_IDX.get(cur_jong_char, -1), _JUNG_IDX[char], 0
+            
+            elif cho_idx != -1:  # 초성만 있는 상태에서 모음
+                if jung_idx == -1:
+                    jung_idx = _JUNG_IDX[char]
+                else:  # 복합 모음 가능성 (ㅗ + ㅏ = ㅘ)
+                    cur_jung = 중성[jung_idx]
+                    if (cur_jung, char) in 복합모음맵:
+                        jung_idx = _JUNG_IDX[복합모음맵[(cur_jung, char)]]
+                    else:
+                        flush()
+                        jung_idx = _JUNG_IDX[char]
+            else:  # 초성 없는 모음 단독
+                if jung_idx != -1:
+                    cur_jung = 중성[jung_idx]
+                    if (cur_jung, char) in 복합모음맵:
+                        jung_idx = _JUNG_IDX[복합모음맵[(cur_jung, char)]]
+                        flush()
+                    else:
+                        flush()
+                        jung_idx = _JUNG_IDX[char]
+                else:
+                    jung_idx = _JUNG_IDX[char]
+
+        # 3. 기타 문자 (숫자, 영문, 특수문자 등)
+        else:
+            flush()
+            result.append(char)
+
+    flush()
+    return "".join(result)
+
+def disassemble(text: str) -> str:
+    """
+    완성형 한글 문자열을 개별 자소 단위로 완전히 분리합니다.
+    (예: '값' -> 'ㄱㅏㅂㅅ', '과' -> 'ㄱㅗㅏ')
+    """
+    result: list[str] = []
+
+    for char in text:
+        # 1. 완성형 한글인 경우 (가 ~ 힣)
+        if '가' <= char <= '힣':
+            num = ord(char) - 0xAC00
+            c = num // 588
+            r = (num % 588) // 28
+            t = num % 28
+
+            # 초성 추가
+            result.append(초성[c])
+
+            # 중성 분리 (ㅘ -> ㅗ, ㅏ)
+            jung_char = 중성[r]
+            if jung_char in _SPLIT_JUNG_MAP:
+                result.extend(_SPLIT_JUNG_MAP[jung_char])
+            else:
+                result.append(jung_char)
+
+            # 종성 분리 (ㄳ -> ㄱ, ㅅ)
+            if t > 0:
+                jong_char = 종성[t]
+                if jong_char in _SPLIT_JONG_MAP:
+                    result.extend(_SPLIT_JONG_MAP[jong_char])
+                else:
+                    result.append(jong_char)
+        
+        # 2. 이미 분리된 자제나 기타 문자인 경우
+        else:
+            if char in _SPLIT_JUNG_MAP:
+                result.extend(_SPLIT_JUNG_MAP[char])
+            elif char in _SPLIT_JONG_MAP:
+                result.extend(_SPLIT_JONG_MAP[char])
+            else:
+                result.append(char)
+
+    return "".join(result)
+
+if __name__ == "__main__":
+    # 1. 복합 문자 분리 테스트
+    print(disassemble("값이"))  # 결과: "ㄱㅏㅂㅅㅇㅣ"
+    
+    # 2. 역변환 (Round-trip) 테스트
+    raw = "값이"
+    dis = disassemble(raw)
+    ass = assemble(dis)
+    print(f"{raw} -> {dis} -> {ass}")  # 결과: 값이 -> ㄱㅏㅂㅅㅇㅣ -> 값이
+    
+    # 3. 복합 모음 테스트
+    print(disassemble("왜 뭐가"))

hangeul-0.1.0/src/hangeul/josa.py

@@ -0,0 +1,103 @@
+import re
+from types import MappingProxyType
+from typing import Final
+
+# 1. 상수 정의
+_JOSA_MAP: Final = MappingProxyType({
+    "이/가": ("가", "이"),
+    "은/는": ("는", "은"),
+    "을/를": ("를", "을"),
+    "와/과": ("와", "과"),
+    "아/야": ("야", "아"),
+    "나/이나": ("나", "이나"),
+    "란/이란": ("란", "이란"),
+    "랑/이랑": ("랑", "이랑"),
+    "라/이라": ("라", "이라"),
+    "예요/이에요": ("예요", "이에요"),
+})
+
+# 로 계열 조사는 'ㄹ' 받침 예외 규칙을 동일하게 공유함
+_RO_JOSAS: Final[tuple[str, ...]] = ("로/으로", "로서/으로서", "로써/으로써", "로부터/으로부터")
+
+# 영문 알파벳 끝글자 발음 데이터 (약어 처리용)
+_ALPHABET_BATTCHIM: MappingProxyType = MappingProxyType({
+    'A': '에이', 'B': '비', 'C': '씨', 'D': '디', 'E': '이',
+    'F': '에프', 'G': '지', 'H': '에이치', 'I': '아이', 'J': '제이',
+    'K': '케이', 'L': '엘', 'M': '엠', 'N': '엔', 'O': '오',
+    'P': '피', 'Q': '큐', 'R': '알', 'S': '에스', 'T': '티',
+    'U': '유', 'V': '브이', 'W': '더블유', 'X': '엑스', 'Y': '와이', 'Z': '제트'
+})
+
+def _get_jong_idx(char: str) -> int:
+    """한글 음절의 종성 인덱스를 반환합니다."""
+    if '가' <= char <= '힣':
+        return (ord(char) - 0xAC00) % 28
+    return -1
+
+def _analyze_last_char(word: str) -> tuple[bool, int]:
+    """
+    단어의 마지막 글자를 분석하여 (받침_여부, 종성_인덱스)를 반환합니다.
+    괄호, 숫자, 영문 약어 처리를 포함합니다.
+    """
+    if not word:
+        return False, -1
+
+    # 1. 괄호 제거: "단어(Content)" -> "단어" 추출
+    base_word = re.sub(r'\(.*\)$', '', word).strip()
+    if not base_word:
+        base_word = word
+    last = base_word[-1]
+
+    # 2. 한글 분석
+    if '가' <= last <= '힣':
+        idx = _get_jong_idx(last)
+        return idx > 0, idx
+
+    # 3. 숫자 분석 (0, 1, 3, 6, 7, 8 은 받침 있음 / 1, 7, 8 은 'ㄹ' 계열)
+    if last.isdigit():
+        has_bat = last in "013678"
+        return has_bat, (8 if last in "178" else (1 if has_bat else 0))
+
+    # 4. 영문 대문자 약어 분석 (예: SDK, AI, SQL)
+    if base_word.isupper() and 'A' <= last <= 'Z':
+        pronunciation = _ALPHABET_BATTCHIM.get(last, "")
+        if pronunciation:
+            idx = _get_jong_idx(pronunciation[-1])
+            return idx > 0, idx
+
+    # 5. 기타 (일반 영문 단어, 특수문자 등)는 받침 없음으로 간주
+    return False, 0
+
+def get_josa(word: str, pattern: str) -> str:
+    """
+    단어와 조사 패턴을 분석하여 적절한 조사를 선택합니다.
+    """
+    if not word:
+        return ""
+
+    has_bat, jong_idx = _analyze_last_char(word)
+    norm_pattern = "/".join(sorted(pattern.split("/")))
+
+    match norm_pattern:
+        # '로' 계열 특수 처리 (받침이 없거나 'ㄹ' 받침인 경우 '로')
+        case p if p in _RO_JOSAS:
+            parts = pattern.split('/') # 사용자 입력 순서 유지
+            # 보통 (로/으로) 또는 (으로/로) 순서임
+            ro, euro = (parts[0], parts[1]) if len(parts[0]) < len(parts[1]) else (parts[1], parts[0])
+            return ro if not has_bat or jong_idx == 8 else euro
+
+        # 일반 조사 처리
+        case p if p in _JOSA_MAP:
+            vowel_case, consonant_case = _JOSA_MAP[p]
+            return consonant_case if has_bat else vowel_case
+
+        # 맵에 없는 패턴은 (받침있음/받침없음) 순서로 가정하여 처리
+        case _:
+            parts = pattern.split('/')
+            if len(parts) != 2:
+                raise ValueError(f"지원하지 않는 조사 패턴입니다: {pattern}")
+            return parts[0] if has_bat else parts[1]
+
+def attach(word: str, pattern: str) -> str:
+    """단어에 조사를 결합합니다."""
+    return f"{word}{get_josa(word, pattern)}"

hangeul-0.1.0/src/hangeul/number.py

@@ -0,0 +1,54 @@
+from typing import Final
+
+_NUM_MAP: Final = {
+    "0": "", "1": "일", "2": "이", "3": "삼", "4": "사",
+    "5": "오", "6": "육", "7": "칠", "8": "팔", "9": "구"
+}
+_UNIT_MAP: Final = ["", "십", "백", "천"]
+_BLOCK_MAP: Final = ["", "만", "억", "조", "경", "해"]
+
+def num2han(number: int | str) -> str:
+    """
+    숫자를 한글 읽기 방식으로 변환합니다.
+    예: 1234 -> "천이백삼십사", 10001 -> "만일"
+    """
+    num_str = str(number).strip().replace(",", "")
+    if not num_str.isdigit():
+        if not num_str: return ""
+        raise ValueError(f"숫자만 입력 가능합니다: {num_str}")
+    
+    if int(num_str) == 0:
+        return "영"
+
+    # 4자리씩 chunk로 쪼갬
+    length = len(num_str)
+    full_str = num_str.zfill(((length - 1) // 4 + 1) * 4)
+    chunks = [full_str[i:i+4] for i in range(0, len(full_str), 4)]
+    
+    result = []
+    num_chunks = len(chunks)
+    
+    for i, chunk in enumerate(chunks):
+        chunk_res = ""
+        for j, digit in enumerate(chunk):
+            if digit == "0":
+                continue
+            
+            unit = _UNIT_MAP[3 - j]
+            val = _NUM_MAP[digit]
+            
+            # '일십', '일백', '일천' -> '십', '백', '천'으로 축약 (단, 일의 자리는 유지)
+            if val == "일" and unit != "":
+                chunk_res += unit
+            else:
+                chunk_res += val + unit
+        
+        if chunk_res:
+            block_unit = _BLOCK_MAP[num_chunks - 1 - i]
+            # '일만' 대신 '만'이 자연스러운 경우 처리
+            if chunk_res == "일" and block_unit == "만":
+                result.append(block_unit)
+            else:
+                result.append(chunk_res + block_unit)
+                
+    return "".join(result)

hangeul-0.1.0/src/hangeul/search.py

@@ -0,0 +1,45 @@
+from .constants import 초성
+from .core import disassemble
+
+def get_chosung(text: str) -> str:
+    """
+    문자열에서 초성만 추출합니다. 
+    한글이 아닌 문자는 그대로 유지합니다.
+    """
+    result = []
+    for char in text:
+        if '가' <= char <= '힣':
+            # 초성 인덱스 계산: (유니코드 - 0xAC00) // (21 * 28)
+            idx = (ord(char) - 0xAC00) // 588
+            result.append(초성[idx])
+        else:
+            result.append(char)
+    return "".join(result)
+
+def matches(target: str, query: str, choseong_only: bool = False) -> bool:
+    """
+    초성 검색 및 자소 단위 검색을 수행합니다.
+    
+    Args:
+        target: 검색 대상 (예: "서강대학교")
+        query: 검색어 (예: "ㅅㄱㄷ" 또는 "서강")
+        choseong_only: True일 경우 검색어가 초성이 아니더라도 강제로 초성 비교를 수행
+    """
+    if not query:
+        return False
+
+    # 1. 검색어가 순수 초성인지 확인 (또는 강제 초성 모드)
+    is_query_chosung = choseong_only or all(c in 초성 for c in query)
+
+    if is_query_chosung:
+        # 대상의 초성과 쿼리를 비교
+        return query in get_chosung(target)
+    
+    # 2. 완성형/자소가 섞인 경우 자소 단위 분해 검색 (예: "ㅎㅏㄴㄱ" 검색 시 "한글" 매칭)
+    return disassemble(query) in disassemble(target)
+
+def search_filter(targets: list[str], query: str) -> list[str]:
+    """
+    리스트에서 검색어에 맞는 항목들을 필터링하여 반환합니다.
+    """
+    return [t for t in targets if matches(t, query)]

hangeul-0.1.0/src/hangeul/similarity.py

@@ -0,0 +1,42 @@
+from .core import disassemble
+
+def _levenshtein_distance(s1: str, s2: str) -> int:
+    """두 문자열 간의 편집 거리(Levenshtein Distance)를 계산합니다."""
+    if len(s1) < len(s2):
+        return _levenshtein_distance(s2, s1)
+
+    if not s2:
+        return len(s1)
+
+    previous_row = range(len(s2) + 1)
+    for i, c1 in enumerate(s1):
+        current_row = [i + 1]
+        for j, c2 in enumerate(s2):
+            insertions = previous_row[j + 1] + 1
+            deletions = current_row[j] + 1
+            substitutions = previous_row[j] + (c1 != c2)
+            current_row.append(min(insertions, deletions, substitutions))
+        previous_row = current_row
+
+    return previous_row[-1]
+
+def jamo_similarity(str1: str, str2: str) -> float:
+    """
+    두 문자열을 자소 단위로 분해하여 유사도(0.0 ~ 1.0)를 측정합니다.
+    1.0에 가까울수록 두 문자열이 유사함을 의미합니다.
+    """
+    if str1 == str2:
+        return 1.0
+    
+    # 자소 단위로 완전히 분해 (예: '값' -> 'ㄱㅏㅂㅅ')
+    s1_dis = disassemble(str1)
+    s2_dis = disassemble(str2)
+    
+    if not s1_dis or not s2_dis:
+        return 0.0
+    
+    distance = _levenshtein_distance(s1_dis, s2_dis)
+    max_len = max(len(s1_dis), len(s2_dis))
+    
+    # 유사도 계산 공식: 1 - (거리 / 최대 길이)
+    return 1.0 - (distance / max_len)

hangeul-0.1.0/src/hangeul.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: hangeul
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pytest>=9.0.3
+
+# hangeul
+
+파이썬 환경에서 한글을 다루기 위한 현대적인 툴킷입니다. 
+
+기존의 파이썬용 한글 라이브러리들은 최신 개발 환경(Type Hinting, Python 3.10+ 등)에 최적화되어 있지 않거나 기능이 파편화되어 있었습니다. hangeul은 조합/분해 오토마타를 기반으로 실무에서 즉시 사용 가능한 강력한 기능들을 통합하여 제공합니다.
+
+---
+
+## 핵심 강점
+
+* **조사(Josa) 처리**: 단순히 받침 유무만 체크하지 않고 영문 약어(SDK, IBM 등)의 발음과 숫자(7, 8 등)의 종성 발음을 인식하여 조사를 선택합니다.
+* **자소 단위 유사도 매칭**: 단어 단위가 아닌 초/중/종성 단위의 편집 거리(Levenshtein Distance)를 계산하여 오타 교정에 최적화된 유사도 점수를 제공합니다.
+* **오토마타 기반 조합/분해**: 연음 법칙을 고려한 조합 로직을 통해 `ㄱㅏㅂㅅㅇㅣ`를 `값이`로 정확히 조립합니다. 
+* **Zero Dependency**: 외부 라이브러리 의존성 없이 파이썬 표준 라이브러리만으로 동작합니다.
+* **Modern Development**: 전 기능에 대한 타입 힌팅을 지원하며, `uv` 및 최신 파이썬 환경에 최적화되어 있습니다.
+
+---
+
+## 주요 기능 및 예제
+
+### 1. 조사(Josa) 결합
+단순 문자열 비교가 아닌 발음 기반의 처리를 수행합니다.
+
+```python
+import hangeul
+
+# 영문 약어 발음 인식
+hangeul.attach("SDK", "은/는")  # "SDK는" (에스디케이 - 받침 없음)
+hangeul.attach("IBM", "이/가")  # "IBM이" (아이비엠 - ㅁ받침)
+
+# 숫자 종성 인식
+hangeul.attach("7", "으로/로")  # "7로" (칠 - ㄹ받침 예외)
+hangeul.attach("10", "을/를")  # "10을" (십 - ㅂ받침)
+
+# 괄호 제거 후 판별
+hangeul.attach("애플(Apple)", "이/가")  # "애플(Apple)이"
+```
+
+### 2. 조합 및 분해 (Assemble / Disassemble)
+한국어 음운 규칙을 따르는 조립과 완전 분해를 지원합니다.
+
+```python
+# 조합 (연음 법칙 적용)
+hangeul.assemble("ㄱㅏㅂㅅㅇㅣ")  # "값이"
+
+# 분해 (겹받침/복합모음 완전 분리)
+hangeul.disassemble("값")  # "ㄱㅏㅂㅅ"
+hangeul.disassemble("과")  # "ㄱㅗㅏ"
+```
+
+### 3. 유사도 분석 및 검색
+오타에 강한 검색 기능을 구현할 때 유용합니다.
+
+```python
+# 자소 단위 유사도 (0.0 ~ 1.0)
+# '값'과 '갑'은 글자 단위에선 0점이지만 자소 단위에선 0.75점입니다.
+hangeul.jamo_similarity("값", "갑")  # 0.75
+
+# 초성 검색 및 부분 일치
+hangeul.matches("서강대학교", "ㅅㄱㄷ")  # True
+hangeul.matches("한글", "ㅎㅏㄴ")  # True
+```
+
+### 4. 숫자 한글 변환
+숫자 단위를 분석하여 관습적인 한글 읽기 방식으로 변환합니다.
+
+```python
+hangeul.num2han(1234567)  # "백이십삼만사천오백육십칠"
+hangeul.num2han(10000)    # "만" (일만 -> 만 축약 적용)
+```
+
+---
+
+## 설치
+
+```bash
+pip install hangeul
+# or
+uv add hangeul
+```
+
+## 환경
+* Python 3.10 이상 권장
+* 의존성 없음 (Standard Library Only)
+
+## 기여 및 문의
+버그 리포트나 기능 제안은 이슈 트래커를 이용해 주세요. High Cohesion, Low Coupling 원칙을 준수하며 관리됩니다.

hangeul-0.1.0/src/hangeul.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+pyproject.toml
+src/hangeul/__init__.py
+src/hangeul/check.py
+src/hangeul/constants.py
+src/hangeul/core.py
+src/hangeul/josa.py
+src/hangeul/number.py
+src/hangeul/search.py
+src/hangeul/similarity.py
+src/hangeul.egg-info/PKG-INFO
+src/hangeul.egg-info/SOURCES.txt
+src/hangeul.egg-info/dependency_links.txt
+src/hangeul.egg-info/requires.txt
+src/hangeul.egg-info/top_level.txt
+tests/test_check.py
+tests/test_core.py
+tests/test_josa.py
+tests/test_num2han.py
+tests/test_search.py
+tests/test_similarity.py

hangeul-0.1.0/src/hangeul.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hangeul-0.1.0/src/hangeul.egg-info/requires.txt

@@ -0,0 +1 @@
+pytest>=9.0.3

hangeul-0.1.0/src/hangeul.egg-info/top_level.txt

@@ -0,0 +1 @@
+hangeul

hangeul-0.1.0/tests/test_check.py

@@ -0,0 +1,56 @@
+import unicodedata
+
+import pytest
+
+from hangeul.check import (
+    is_han, is_pure_han, has_batchim, can_cho, can_jung, can_jong, normalize
+)
+
+
+def test_is_pure_han():
+    assert is_pure_han("가나다") is True
+    assert is_pure_han("ㄱㄴㄷ") is True
+    assert is_pure_han("가나12") is False
+    assert is_pure_han("Hello") is False
+
+def test_is_han_options():
+    # 공백 허용 테스트
+    assert is_han("가나 다", allow_space=True) is True
+    assert is_han("가나 다", allow_space=False) is False
+    
+    # 문장 부호 허용 테스트
+    assert is_han("안녕!", allow_punctuation=True) is True
+    assert is_han("안녕!", allow_punctuation=False) is False
+    
+    # 혼합 테스트
+    assert is_han("반가워, 친구야!", allow_space=True, allow_punctuation=True) is True
+
+def test_has_batchim():
+    assert has_batchim("강") is True
+    assert has_batchim("가") is False
+    assert has_batchim(" ") is False
+    assert has_batchim("ㄱ") is False
+
+def test_can_functions():
+    assert can_cho("ㄱ") is True
+    assert can_cho("ㅏ") is False
+    assert can_jung("ㅏ") is True
+    assert can_jong("ㄳ") is True
+    assert can_jong("ㄸ") is False
+
+def test_normalize():
+    nfd_text = unicodedata.normalize('NFD', '한글')
+    # 눈으로 보기엔 같지만 길이는 다름 (ㅎ, ㅏ, ㄴ, ㄱ, ㅡ, ㄹ = 6)
+    assert len(nfd_text) == 6
+    # NFC로 정규화
+    nfc_text = normalize(nfd_text, form='NFC')
+    assert len(nfc_text) == 2
+    assert nfc_text == '한글'
+
+    nfc_text = '한글'
+    nfd_text = normalize(nfc_text, form='NFD')
+    assert len(nfd_text) == 6
+
+    with pytest.raises(Exception):
+        normalize(123)
+        normalize(None)

hangeul-0.1.0/tests/test_core.py

@@ -0,0 +1,31 @@
+from hangeul.core import assemble, disassemble, qwerty2han
+
+def test_qwerty2han():
+    assert qwerty2han("gksrmf") == "ㅎㅏㄴㄱㅡㄹ"
+    assert qwerty2han("R r") == "ㄲ ㄱ"
+    assert qwerty2han("123!@#") == "123!@#"
+
+def test_assemble_basic():
+    assert assemble("ㄱㅏ") == "가"
+    assert assemble("ㄱㅏㄴ") == "간"
+    assert assemble("ㄱㅏㅂㅅ") == "값"
+    assert assemble("ㅗㅏ") == "ㅘ"
+
+def test_assemble_liaison():
+    """연음 법칙 및 겹받침 분리 테스트"""
+    assert assemble("ㄱㅏㅂㅅㅇㅣ") == "값이"
+    assert assemble("ㄱㅏㅂㅅㅣ") == "갑시"
+    assert assemble("ㅇㅏㄴㅈㅇㅏ") == "앉아"
+    assert assemble("ㅇㅗㅐㅇㅏㄴㄷㅗㅣ") == "왜안되"
+
+def test_disassemble():
+    assert disassemble("한글") == "ㅎㅏㄴㄱㅡㄹ"
+    assert disassemble("값") == "ㄱㅏㅂㅅ"
+    assert disassemble("과") == "ㄱㅗㅏ"
+    assert disassemble("왜") == "ㅇㅗㅐ"
+
+def test_round_trip():
+    """조합 후 분해했을 때 원본과 동일한지 확인"""
+    targets = ["한글", "값이", "앉아", "도전", "학교"]
+    for t in targets:
+        assert assemble(disassemble(t)) == t

hangeul-0.1.0/tests/test_josa.py

@@ -0,0 +1,34 @@
+from hangeul.josa import attach, get_josa
+
+def test_josa_basic():
+    assert attach("사과", "이/가") == "사과가"
+    assert attach("수박", "이/가") == "수박이"
+    assert attach("바다", "은/는") == "바다는"
+    assert attach("강", "은/는") == "강은"
+
+def test_josa_ro_exception():
+    """'로/으로'의 ㄹ 받침 예외 테스트"""
+    assert attach("강", "으로/로") == "강으로"
+    assert attach("물", "으로/로") == "물로"
+    assert attach("길", "으로/로") == "길로"
+
+def test_josa_number():
+    """숫자 발음 기반 조사 테스트"""
+    assert attach("1", "이/가") == "1이"   # 일-이
+    assert attach("2", "이/가") == "2가"   # 이-가
+    assert attach("3", "은/는") == "3은"   # 삼-은
+    assert attach("7", "로/으로") == "7로" # 칠-로 (ㄹ받침)
+    assert attach("8", "로/으로") == "8로" # 팔-로 (ㄹ받침)
+    assert attach("10", "을/를") == "10을" # 십-을
+
+def test_josa_alphabet_acronym():
+    """영문 대문자 약어 테스트"""
+    assert attach("IBM", "이/가") == "IBM이" # 아이비엠(ㅁ받침)
+    assert attach("AI", "이/가") == "AI가"   # 에이아이(받침없음)
+    assert attach("SDK", "은/는") == "SDK는" # 에스디케이(받침없음)
+    assert attach("SQL", "로/으로") == "SQL로" # 에스큐엘(ㄹ받침)
+
+def test_josa_parentheses():
+    """괄호 처리 테스트"""
+    assert attach("애플(Apple)", "이/가") == "애플(Apple)이"
+    assert attach("삼성(Samsung)", "은/는") == "삼성(Samsung)은"

hangeul-0.1.0/tests/test_num2han.py

@@ -0,0 +1,22 @@
+import pytest
+from hangeul.number import num2han
+
+def test_num2han():
+    # 기본 변환
+    assert num2han(1234) == "천이백삼십사"
+    assert num2han(1010) == "천십"
+    
+    # 만 단위 축약 (일만 -> 만)
+    assert num2han(10000) == "만"
+    assert num2han(15000) == "만오천"
+    
+    # 억 단위 (일억 유지)
+    assert num2han(100000000) == "일억"
+    
+    # 큰 숫자 및 0 처리
+    assert num2han(0) == "영"
+    assert num2han(200010) == "이십만십"
+    
+    # 에러 처리
+    with pytest.raises(ValueError):
+        num2han("123a")

hangeul-0.1.0/tests/test_search.py

@@ -0,0 +1,18 @@
+from hangeul.search import matches, search_filter
+
+def test_chosung_matches():
+    target = "서강대학교"
+    assert matches(target, "ㅅㄱㄷ") is True
+    assert matches(target, "ㅅㄱㄷㅎㄱ") is True
+    assert matches(target, "ㅎㅇㄷ") is False
+
+def test_jaso_matches():
+    target = "한글"
+    assert matches(target, "ㅎㅏㄴ") is True
+    assert matches(target, "ㅎㅏㄴㄱㅡㄹ") is True
+    assert matches(target, "ㅎㅡㄹ") is False
+
+def test_search_filter():
+    list_data = ["사과", "수박", "복숭아", "포도"]
+    assert search_filter(list_data, "ㅅㅂ") == ["수박"]
+    assert search_filter(list_data, "ㅅ") == ["사과", "수박", "복숭아"]

hangeul-0.1.0/tests/test_similarity.py

@@ -0,0 +1,10 @@
+from hangeul import jamo_similarity
+
+def test_jamo_similarity():
+    assert jamo_similarity("파이썬", "파이썬") == 1.0
+    
+    assert jamo_similarity("안녕", "안녀") > 0.8
+    
+    assert jamo_similarity("사과", "자동차") < 0.5
+    
+    assert jamo_similarity("사람", "사5람") > 0.8