Metadata-Version: 2.4
Name: es-hangul
Version: 0.1.0
Summary: Python port of es-hangul: Korean Hangul processing library
Project-URL: Homepage, https://github.com/dogbull/es-hangul
Project-URL: Repository, https://github.com/dogbull/es-hangul
Project-URL: Original (TypeScript), https://github.com/toss/es-hangul
License-Expression: MIT
Keywords: assemble,disassemble,hangul,josa,korean,pronunciation,romanize
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Korean
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# es-hangul-py

한국어 한글 처리 Python 라이브러리.

## 원본

이 라이브러리는 **[es-hangul](https://github.com/toss/es-hangul)** (TypeScript)을 Python으로 포팅한 것입니다.

- 원본 저장소: https://github.com/toss/es-hangul
- 원본 문서: https://es-hangul.slash.page/
- 원본 라이선스: MIT
- 원본 언어: TypeScript
- 포팅 언어: Python 3.10+

es-hangul은 [Toss](https://toss.im)에서 개발한 오픈소스 한글 처리 라이브러리로,
한글 분해/조합, 조사 선택, 숫자 변환, 발음 변환, 키보드 변환 등의 기능을 제공합니다.
이 패키지는 동일한 기능을 Python 환경에서 사용할 수 있도록 구현했습니다.

## 설치

```bash
pip install es-hangul
```

## 기능 목록

| 분류 | 함수 | 설명 |
|------|------|------|
| 핵심 | `disassemble` | 한글 문자열 분해 |
| 핵심 | `disassemble_complete_character` | 완성형 한글 낱자 분해 |
| 핵심 | `disassemble_to_groups` | 어절 단위로 분해 |
| 핵심 | `assemble` | 자모 조합 |
| 핵심 | `combine_character` | 초성/중성/종성으로 완성자 조합 |
| 핵심 | `combine_vowels` | 모음 조합 |
| 핵심 | `get_choseong` | 초성 추출 |
| 핵심 | `has_batchim` | 받침 유무 확인 |
| 핵심 | `can_be_choseong` | 초성 가능 여부 |
| 핵심 | `can_be_jungseong` | 중성 가능 여부 |
| 핵심 | `can_be_jongseong` | 종성 가능 여부 |
| 핵심 | `josa` | 조사 선택 |
| 핵심 | `remove_last_character` | 마지막 글자 제거 |
| 키보드 | `convert_qwerty_to_hangul` | 영문 → 한글 변환 |
| 키보드 | `convert_hangul_to_qwerty` | 한글 → 영문 변환 |
| 키보드 | `convert_qwerty_to_alphabet` | QWERTY → 영문자 변환 |
| 숫자 | `number_to_hangul` | 숫자 → 한글 (일억이천...) |
| 숫자 | `number_to_hangul_mixed` | 숫자 → 한글 혼합 (1억 2천...) |
| 숫자 | `amount_to_hangul` | 금액 문자열 → 한글 |
| 숫자 | `susa` | 수사 (하나, 둘, 셋...) |
| 숫자 | `seosusa` | 서수사 (첫째, 둘째...) |
| 숫자 | `days` | 날 수 한글 표현 (하루, 이틀...) |
| 발음 | `standardize_pronunciation` | 표준 발음 변환 |
| 발음 | `romanize` | 로마자 표기 변환 |

## 사용 예시

### 한글 분해 / 조합

```python
from es_hangul import disassemble, assemble, combine_character

disassemble("안녕")
# => 'ㅇㅏㄴㄴㅕㅇ'

assemble(['ㅎ', 'ㅏ', 'ㄴ', 'ㄱ', 'ㅡ', 'ㄹ'])
# => '한글'

combine_character('ㅎ', 'ㅏ', 'ㄴ')
# => '한'
```

### 초성 추출

```python
from es_hangul import get_choseong

get_choseong("안녕하세요")
# => 'ㅇㄴㅎㅅㅇ'

get_choseong("띄어 쓰기")
# => 'ㄷ ㅆㄱ'
```

### 받침 확인

```python
from es_hangul import has_batchim

has_batchim("한")   # => True
has_batchim("하")   # => False
```

### 조사 선택

```python
from es_hangul import josa

josa("사과", "을/를")   # => '사과를'
josa("바나나", "을/를") # => '바나나를'
josa("닭", "을/를")     # => '닭을'

# 조사만 반환
josa.pick("사과", "을/를")   # => '를'
josa.pick("닭", "을/를")     # => '을'
```

지원하는 조사 목록:
`이/가`, `을/를`, `은/는`, `으로/로`, `와/과`, `이나/나`, `이란/란`,
`아/야`, `이랑/랑`, `이에요/예요`, `으로서/로서`, `으로써/로써`,
`으로부터/로부터`, `이라/라`

### 키보드 변환

```python
from es_hangul import convert_qwerty_to_hangul, convert_hangul_to_qwerty

convert_qwerty_to_hangul("dkssud")   # => '안녕'
convert_hangul_to_qwerty("안녕")     # => 'dkssud'
```

### 숫자 → 한글

```python
from es_hangul import number_to_hangul, number_to_hangul_mixed, susa, seosusa

number_to_hangul(1234)         # => '천이백삼십사'
number_to_hangul_mixed(1234)   # => '1천2백3십4'

susa(3)          # => '셋'
susa(3, True)    # => '세'   (수관형사: "세 마리")

seosusa(1)       # => '첫째'
seosusa(3)       # => '셋째'
```

### 표준 발음 / 로마자 표기

```python
from es_hangul import standardize_pronunciation, romanize

standardize_pronunciation("닭볶음")   # => '닥뽁끔'
standardize_pronunciation("먹는")     # => '멍는'

romanize("안녕하세요")   # => 'annyeonghaseyo'
romanize("백마")         # => 'baengma'
romanize("신라")         # => 'silla'
```

## 개발

```bash
# 의존성 설치
pip install -e ".[dev]"

# 테스트 실행
pytest

# 커버리지 포함
pytest --cov=es_hangul
```

## 라이선스

MIT

원본 es-hangul의 라이선스를 따릅니다.
원본 저작권: [Toss](https://github.com/toss) and es-hangul contributors
