Metadata-Version: 2.4
Name: matchum
Version: 0.2.0
Summary: 규칙 기반 오프라인 한국어 맞춤법 검사 라이브러리
Author: Juwon Seo (서주원, OMEGA SYSTEMS)
License-Expression: MIT
Project-URL: Homepage, https://github.com/sjw0328/matchum
Project-URL: Issues, https://github.com/sjw0328/matchum/issues
Project-URL: Source, https://github.com/sjw0328/matchum
Project-URL: Changelog, https://github.com/sjw0328/matchum#변경-이력
Project-URL: Author, https://github.com/sjw0328
Project-URL: DOI, https://doi.org/10.5281/zenodo.23531936
Keywords: korean,spell-checker,spell-check,hangul,맞춤법,맞춤법 검사기,한국어,hanspell,py-hanspell,nlp,offline
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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: Natural Language :: Korean
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# matchum (맞춤)

[![PyPI](https://img.shields.io/pypi/v/matchum)](https://pypi.org/project/matchum/) [![OpenSSF Baseline](https://www.bestpractices.dev/projects/15483/baseline)](https://www.bestpractices.dev/en/projects/15483/baseline-1) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23531936.svg)](https://doi.org/10.5281/zenodo.23531936)

로컬에서 동작하는 규칙 기반 한국어 맞춤법 검사 파이썬 라이브러리입니다.

> **English:** matchum is a rule-based, offline Korean spell checker for Python. It is designed to run locally using only the standard library, and includes a compatibility layer for code written against `py-hanspell`. Early (0.x) version; results are for reference only.

- 외부 서비스에 접속하지 않는 방식으로 설계되었습니다.
- 파이썬 표준 라이브러리만 사용합니다.
- 기존 `py-hanspell` 코드를 import 한 줄만 바꿔 옮길 수 있는 호환 계층을 포함합니다.

> **개발 초기(0.x) 버전입니다.**
> 등록된 규칙에 해당하는 표기만 검출하며, 문맥을 이해하지 않습니다.
> 검출 누락과 잘못된 교정이 있을 수 있으므로, 결과는 참고용으로만 사용하고 최종 판단은 사용자가 직접 하시기 바랍니다.
> 버전이 올라가면서 API와 규칙이 예고 없이 바뀔 수 있습니다.

## 설치

```bash
pip install matchum
```

Python 3.9 이상에서 개발·테스트했습니다.

## 사용법

### 기본

```python
from matchum import check

r = check("몇일 뒤에 연락할께요. 나도 할수있다.")

r.checked   # '며칠 뒤에 연락할게요. 나도 할 수 있다.'
r.errors    # 3

for c in r.corrections:
    print(c.original, "→", c.suggestion, "|", c.message)
```

`Result`의 주요 속성은 다음과 같습니다.

| 속성 | 내용 |
|---|---|
| `original` | 원문 |
| `checked` | 교정문 (`ERROR` 수준만 반영, 아래 참고) |
| `corrections` | `Correction` 목록 (원문 위치, 원래 표기, 제안, 규칙 ID, 메시지, 수준, 분류) |
| `errors` | 검출 건수 |
| `as_dict()` | 위 내용을 dict로 반환 |

### 교정 수준

| 수준 | 의미 | `checked` 반영 |
|---|---|---|
| `ERROR` | 문맥과 관계없이 틀린 표기로 등록된 규칙 | 반영 |
| `WARNING` | 문맥에 따라 맞을 수도 있는 표기 (외래어, 이중 피동 등) | `check(text, apply_warnings=True)`일 때만 반영 |

### 사용자 설정

```python
from matchum import Checker, Category, WordRule

checker = Checker(
    ignore=["됬"],                       # 교정하지 않을 원문 표기
    disabled=["spacing.002"],            # 끌 규칙 ID
    categories=[Category.SPELLING],      # 특정 분류만 검사 (SPELLING / SPACING / STYLE)
).add_rule(WordRule("my.001", "어케", "어떻게"))

checker.check("어케 됬어").checked   # '어떻게 됬어'
```

### py-hanspell 호환 계층

```python
# from hanspell import spell_checker
from matchum import spell_checker

result = spell_checker.check("몇일 뒤에 봐요")
result.checked      # '며칠 뒤에 봐요'
result.as_dict()
```

반환 형식을 비슷하게 맞춘 것이며, 검사 결과는 원래 라이브러리와 다를 수 있습니다.
`words` 항목의 어절별 상태는 근사값입니다.

### 명령줄

```bash
matchum "몇일 뒤에 연락할께요"
matchum -f 원고.txt --json
echo "할수있다" | matchum
```

검출이 있으면 종료 코드 1, 없으면 0을 반환합니다.

## 규칙 구성 (0.2.0 기준, 규칙 약 770개)

| 분류 | 예시 |
|---|---|
| 되/돼·활용형 | 됬→됐, 치뤘다→치렀다, 담궜다→담갔다, 서슴치→서슴지 |
| 부사 | 곰곰히→곰곰이, 깊숙히→깊숙이, 여지껏→여태껏 |
| 명사·성어 | 윗층→위층, 눈꼽→눈곱, 순대국→순댓국, 실업율→실업률 |
| 어미 | 할께→할게, 하던지 말던지→하든지 말든지, 책이예요→책이에요 |
| 띄어쓰기 | 할수있다→할 수 있다, 너때문에→너 때문에, 하지않다→하지 않다, 보고싶다→보고 싶다 |
| 외래어 (WARNING) | 메세지→메시지, 컨텐츠→콘텐츠 |
| 문맥 의존 (WARNING) | 바램, 일부로, 잊혀지다, 뒤쳐지다 |

전체 목록은 `matchum.py`의 규칙 표에서 확인할 수 있습니다.

### 다루지 못하는 것

- 뜻으로 갈리는 표기 (로서/로써, 맞추다/맞히다, 든지/던지 등)
- 규칙에 등록되지 않은 오류
- 문장 단위의 문법·어순·문체

## 규칙 데이터에 관하여

교정 쌍은 현행 한글 맞춤법·표준어 규정·외래어 표기법을 참고해 작성했으며, 교정 메시지는 직접 작성했습니다.
이 라이브러리의 규칙은 공식 기관의 판정이 아니며, 어문 규범이 개정되면 실제 기준과 달라질 수 있습니다.

## 문제 신고·기여

잘못된 교정(오탐)이나 누락된 오류는 GitHub 이슈로 알려 주세요.
이슈와 PR에 대한 응답·반영 여부와 시점은 메인테이너의 판단에 따릅니다.

### 기여물의 권리

이 저장소에 이슈, PR, 규칙 데이터, 코드, 문서 등(이하 "기여물")을 제출하면 기여자는 다음에 동의한 것으로 봅니다.

1. 기여물은 이 프로젝트의 MIT License로 배포되며, 메인테이너는 이를 수정·재배포·재라이선스할 수 있습니다.
2. 기여자는 기여물을 제출할 권리를 가지고 있으며, 제3자의 저작권·특허·영업비밀 등을 침해하지 않습니다.
3. 다른 사전, 맞춤법 검사기, 웹사이트, 서적 등의 해설문·예문·데이터를 복사해 제출하지 않습니다.
4. 기여물로 인해 제3자와 분쟁이 생기면 그 책임은 기여자에게 있습니다.
5. 기여물에 대한 보상이나 표기는 요구할 수 없으며, 반영 여부와 방식은 메인테이너가 정합니다.

### 오탐·누락 신고

이슈에 아래 내용을 적어 주세요.

- 입력 문장
- 실제 결과 (`matchum --json "문장"` 출력)
- 기대 결과와 근거

개인정보나 민감한 내용이 포함된 문장은 올리지 마세요.

### 규칙 추가

1. 대부분의 규칙은 `matchum.py`의 사전형 규칙 표에 `(오표기, 교정어[, 옵션])` 한 줄을 넣어 만듭니다.
2. 오표기가 다른 정상 단어의 일부로 나올 수 있으면 `word_start` 또는 `exceptions` 옵션을 씁니다.
3. 문맥에 따라 맞을 수도 있는 표기는 `_CONTEXT` 표(WARNING)에 넣습니다.
4. 교정 메시지는 직접 작성합니다.
5. `test_matchum.py`의 `CASES`(교정 케이스)와 `CLEAN`(오탐 방지 케이스)에 예문을 추가합니다.

### 테스트

```bash
pip install pytest
pytest
```

### 보안 관련 신고

보안상 문제로 판단되는 사항은 공개 이슈 대신 seodes105@gmail.com 으로 알려 주세요.

- 이 프로젝트는 개인이 비영리로 관리합니다.
- 응답 여부, 응답 시점, 수정 여부와 시점은 메인테이너의 판단에 따르며, 정해진 처리 기한은 두지 않습니다.
- 수정 사항은 최신 버전에만 반영될 수 있습니다.

이 소프트웨어는 MIT License에 따라 "있는 그대로(AS IS)" 제공됩니다.

## 관련 없음 고지

이 프로젝트는 국립국어원, 네이버, `py-hanspell` 프로젝트와 관련이 없으며, 이들로부터 승인이나 지원을 받지 않았습니다.
언급된 이름은 각 소유자의 것입니다.

## 변경 이력

### 0.2.0

- 규칙 약 230개 → 약 770개로 확대 (활용형·부사·어휘·사이시옷·-율/-률·외래어·어미·띄어쓰기)
- 표준어 규정(1988년 문교부 고시)의 표준어/비표준어 대응 중 현재도 쓰이는 표기 일부를 반영
- 띄어쓰기 규칙 추가: `때문`, `-ㄹ 수밖에`, `것 같다`, `-지 않다`, `-고 싶다/있다`, 조사 붙여 쓰기 등
- 기존 규칙 오탐 수정 (`전문가만이`, `계속비로서`, `보잘것없다`, `깔때기`, `껄껄`, `구지레하다` 등)
- 숫자 바로 뒤도 단어 첫머리로 보도록 변경 (`1일부로` 오탐 방지)

### 0.1.1 — 2026-10-14

- 교정 메시지의 조사를 받침에 맞게 표시 (`'며칠'이`, `'안 되'가`)
- `안 하다` 띄어쓰기 규칙 추가 (안하기로 → 안 하기로)
- `-ㄹ께라고` 형태 검출 (연락할께라고 → 연락할게라고)
- 예외 단어가 다른 단어 안에 있을 때 잘못 적용되던 문제 수정 (끝날것 → 끝날 것)
- PyPI 페이지에 README가 표시되도록 패키지 설정 수정

### 0.1.0 — 2026-10-13

- 첫 공개 버전 (규칙 234개, py-hanspell 호환 계층, 명령줄 도구)

## 인용

Zenodo에 보관되어 있습니다. 인용 정보는 저장소의 `CITATION.cff`(GitHub 오른쪽의 "Cite this repository")를 참고하십시오.

- 모든 버전 DOI: [10.5281/zenodo.23531936](https://doi.org/10.5281/zenodo.23531936)
- 0.1.3 DOI: [10.5281/zenodo.23531937](https://doi.org/10.5281/zenodo.23531937)

## 라이선스

MIT License (저장소의 LICENSE 파일 참고)

이 소프트웨어는 "있는 그대로(AS IS)" 제공되며, 상품성·특정 목적 적합성·비침해를 포함한 어떠한 명시적·묵시적 보증도 하지 않습니다.
이 소프트웨어의 사용 또는 사용 불능으로 발생하는 손해나 분쟁에 대해 저작자와 기여자는 책임을 지지 않습니다.
검사 결과를 문서 제출, 출판, 시험, 법적·공식 문서 등에 사용할 경우 그 결과에 대한 책임은 사용자에게 있습니다.

## 만든 사람

서주원 (Juwon Seo, OMEGA SYSTEMS) · [GitHub @sjw0328](https://github.com/sjw0328) · <https://pinnn.me/@seodes105>
라이선스 문의: seodes105@gmail.com
