matchum (맞춤)

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

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와 규칙이 예고 없이 바뀔 수 있습니다.

설치

pip install matchum

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

사용법

기본

from matchum import check

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

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

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

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

교정 수준

사용자 설정

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 호환 계층

# from hanspell import spell_checker
from matchum import spell_checker

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

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

명령줄

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

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

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

전체 목록은 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(오탐 방지 케이스)에 예문을 추가합니다.

테스트

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
• 0.1.3 DOI: 10.5281/zenodo.23531937

라이선스

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

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

만든 사람

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