korean-datetime 1.0.0__py3-none-any.whl

korean_datetime/__init__.py

@@ -0,0 +1,58 @@
+"""
+korean_datetime: 한국어 날짜·시간·혼합 표현 추출·정규화 (표준 라이브러리만 사용)
+
+    >>> from datetime import datetime
+    >>> from korean_datetime import parse
+    >>> parse("다음주 월요일 저녁 7시 반", now=datetime(2026, 9, 28, 14, 30)).start
+    datetime.datetime(2026, 10, 5, 19, 30)
+"""
+
+from .core import current_reference, reference_time
+from .temporal import (
+    Ambiguity,
+    AmbiguousHour,
+    BuiltinHolidays,
+    ChainedHolidays,
+    Cycle,
+    DateTableHolidays,
+    Direction,
+    Grain,
+    HolidayCalendar,
+    Kind,
+    ParseOptions,
+    TemporalExpression,
+    TemporalParser,
+    lunar_to_solar,
+    parse,
+    parse_all,
+    parse_date,
+    parse_datetime,
+    parse_time,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Ambiguity",
+    "AmbiguousHour",
+    "BuiltinHolidays",
+    "ChainedHolidays",
+    "Cycle",
+    "DateTableHolidays",
+    "Direction",
+    "Grain",
+    "HolidayCalendar",
+    "Kind",
+    "ParseOptions",
+    "TemporalExpression",
+    "TemporalParser",
+    "__version__",
+    "current_reference",
+    "lunar_to_solar",
+    "parse",
+    "parse_all",
+    "parse_date",
+    "parse_datetime",
+    "parse_time",
+    "reference_time",
+]

korean_datetime/__main__.py

@@ -0,0 +1,61 @@
+"""명령행: 날짜/시간 표현을 JSON Lines로 출력
+
+    $ python -m korean_datetime "내일 저녁 7시" --now 2026-09-28T14:30
+    {"text": "내일 저녁 7시", ..., "value": "2026-09-29T19:00:00", ...}
+
+인식 결과가 없으면 종료 코드 1.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from datetime import datetime
+
+from .temporal import AmbiguousHour, Cycle, ParseOptions, TemporalParser
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="korean-datetime", description="한국어 날짜/시간 표현 정규화")
+    parser.add_argument("text", nargs="?", help="분석할 텍스트 (생략하면 표준 입력)")
+    parser.add_argument("--now", help="기준 시각 (ISO 8601, 예: 2026-09-28T14:30). 기본: 현재 시각")
+    parser.add_argument("--all", action="store_true", help="모든 표현 출력 (기본: 첫 표현만)")
+    parser.add_argument(
+        "--ambiguous-hour", choices=[p.value for p in AmbiguousHour], default="nearest_future"
+    )
+    parser.add_argument(
+        "--cycle",
+        choices=[c.value for c in Cycle],
+        default=Cycle.FUTURE.value,
+        help="생략된 연/월/날짜의 주기",
+    )
+    parser.add_argument("--compact-dates", action="store_true", help="1015, 261015 같은 숫자를 날짜로 인식")
+    parser.add_argument("--vague", action="store_true", help="'최근', '향후' 같은 막연한 때도 인식")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arg_parser = _build_arg_parser()
+    args = arg_parser.parse_args(argv)
+    try:
+        now = datetime.fromisoformat(args.now) if args.now else None
+    except ValueError:
+        arg_parser.error(f"--now 형식이 올바르지 않습니다: {args.now!r}")
+    options = ParseOptions(
+        cycle=Cycle(args.cycle),
+        ambiguous_hour=AmbiguousHour(args.ambiguous_hour),
+        compact_dates=args.compact_dates,
+        vague=args.vague,
+    )
+    text = args.text if args.text is not None else sys.stdin.read()
+    parser = TemporalParser(options)
+    results = parser.parse_all(text, now) if args.all else [r for r in [parser.parse(text, now)] if r]
+    for result in results:
+        print(json.dumps(result.to_dict(), ensure_ascii=False))
+    return 0 if results else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

korean_datetime/core/__init__.py

@@ -0,0 +1,29 @@
+"""날짜/시간 파서가 쓰는 내부 기반
+
+- scanner: 한국어 단어 경계·조사를 인식하는 정규식 토큰 스캐너
+- numerals: 한글 수사 파서 ('이십삼', '스물세')
+- clock: 기준 시각 (요청 단위 reference_time)
+- evaluation: 정답셋 기반 정량 평가
+"""
+
+from .clock import current_reference, reference_time
+from .evaluation import EvaluationReport, GoldCase, Metrics, evaluate, load_gold
+from .numerals import parse_korean_number, parse_native, parse_sino
+from .scanner import Scanner, Split, Token, TokenRule
+
+__all__ = [
+    "EvaluationReport",
+    "GoldCase",
+    "Metrics",
+    "Scanner",
+    "Split",
+    "Token",
+    "TokenRule",
+    "current_reference",
+    "evaluate",
+    "load_gold",
+    "parse_korean_number",
+    "parse_native",
+    "parse_sino",
+    "reference_time",
+]

korean_datetime/core/clock.py

@@ -0,0 +1,50 @@
+"""기준 시각 — 상대 표현('내일', '3시', '1시간 후')을 계산하는 기준
+
+우선순위:
+    1. 함수에 넘긴 now
+    2. reference_time()으로 정한 요청 단위 기준 시각
+    3. 서버 시각 (시간대를 지정했으면 그 시간대로)
+
+웹 서버에서는 요청마다 한 번 정해 두면, 그 요청 안의 모든 호출이 now 없이 같은 기준을 씁니다.
+
+    @app.middleware("http")
+    async def set_request_time(request, call_next):
+        with reference_time(datetime.now(KST)):
+            return await call_next(request)
+
+ContextVar 기반이라 스레드·비동기 요청끼리 섞이지 않습니다.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import date, datetime, tzinfo
+
+_REFERENCE: ContextVar[datetime | None] = ContextVar("korean_datetime_reference_time", default=None)
+
+
+def _as_datetime(value: datetime | date) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day)
+    raise TypeError(f"기준 시각은 datetime 또는 date여야 합니다: {type(value).__name__}")
+
+
+@contextmanager
+def reference_time(value: datetime | date) -> Iterator[datetime]:
+    """블록 안에서 now를 생략한 호출이 쓸 기준 시각을 정합니다. 블록을 나오면 이전 값으로 돌아갑니다."""
+    moment = _as_datetime(value)
+    token = _REFERENCE.set(moment)
+    try:
+        yield moment
+    finally:
+        _REFERENCE.reset(token)
+
+
+def current_reference(tz: tzinfo | None = None) -> datetime:
+    """reference_time()으로 정한 기준 시각. 없으면 서버 시각 (tz가 있으면 그 시간대)."""
+    fixed = _REFERENCE.get()
+    return fixed if fixed is not None else datetime.now(tz)

korean_datetime/core/evaluation.py

@@ -0,0 +1,189 @@
+"""정답셋(gold) 기반 정량 평가 (값 하나를 예측하는 파서 공용)
+
+정답셋은 JSONL입니다. 첫 줄에 `{"_meta": {"now": "..."}}`로 기본 기준 시각을 둘 수 있고,
+각 줄은 `{"category": str, "text": str, "expected": {...} | null, "now"?: str}` 형식입니다.
+expected가 null이면 "아무것도 인식하지 않아야 함"(음성 케이스)입니다.
+
+지표:
+- 검출: TP(정답 있음·예측 있음), FN(정답 있음·예측 없음), FP(정답 없음·예측 있음), TN
+- precision = TP/(TP+FP), recall = TP/(TP+FN), F1
+- value_accuracy = 값까지 맞은 TP / TP (검출한 것 중 정규화가 맞은 비율)
+- accuracy = (값까지 맞은 TP + TN) / 전체
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+Expected = Mapping[str, Any]
+Prediction = Any  # 예측 결과 (예: TemporalExpression). None이면 인식하지 않음
+Predict = Callable[[str, datetime], Prediction | None]
+Match = Callable[[Prediction, Expected], bool]
+
+
+@dataclass(frozen=True, slots=True)
+class GoldCase:
+    text: str
+    expected: Expected | None
+    category: str
+    now: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class Metrics:
+    tp: int = 0
+    fp: int = 0
+    fn: int = 0
+    tn: int = 0
+    correct: int = 0
+
+    @property
+    def total(self) -> int:
+        return self.tp + self.fp + self.fn + self.tn
+
+    @property
+    def precision(self) -> float:
+        return self.tp / (self.tp + self.fp) if self.tp + self.fp else 1.0
+
+    @property
+    def recall(self) -> float:
+        return self.tp / (self.tp + self.fn) if self.tp + self.fn else 1.0
+
+    @property
+    def f1(self) -> float:
+        p, r = self.precision, self.recall
+        return 2 * p * r / (p + r) if p + r else 0.0
+
+    @property
+    def value_accuracy(self) -> float:
+        """검출한 것(TP) 중 값까지 맞은 비율 — 정규화 품질"""
+        return (self.correct - self.tn) / self.tp if self.tp else 1.0
+
+    @property
+    def accuracy(self) -> float:
+        return self.correct / self.total if self.total else 1.0
+
+    def add(self, result: CaseResult) -> Metrics:
+        expected, predicted = result.case.expected is not None, result.predicted is not None
+        return Metrics(
+            tp=self.tp + (expected and predicted),
+            fp=self.fp + (not expected and predicted),
+            fn=self.fn + (expected and not predicted),
+            tn=self.tn + (not expected and not predicted),
+            correct=self.correct + result.correct,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CaseResult:
+    case: GoldCase
+    predicted: Prediction | None
+    correct: bool
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class EvaluationReport:
+    results: tuple[CaseResult, ...]
+    overall: Metrics
+    by_category: Mapping[str, Metrics] = field(default_factory=dict)
+
+    @property
+    def failures(self) -> list[CaseResult]:
+        return [r for r in self.results if not r.correct]
+
+    def format(self, max_failures: int = 20) -> str:
+        columns = ("precision", 11), ("recall", 8), ("f1", 7), ("value_acc", 11), ("accuracy", 10)
+        header = f"{'category':<18}{'n':>7}" + "".join(f"{name:>{width}}" for name, width in columns)
+        rows = [header, "-" * len(header)]
+        items = [*sorted(self.by_category.items()), ("TOTAL", self.overall)]
+        for name, m in items:
+            rows.append(
+                f"{name:<18}{m.total:>7}{m.precision:>11.3f}{m.recall:>8.3f}{m.f1:>7.3f}"
+                f"{m.value_accuracy:>11.3f}{m.accuracy:>10.3f}"
+            )
+        failures = self.failures
+        rows.append(f"실패 {len(failures)}건")
+        rows.extend(
+            f"  [{r.case.category}] {r.case.text!r} @ {r.case.now:%Y-%m-%d %H:%M}: {r.detail}"
+            for r in failures[:max_failures]
+        )
+        return "\n".join(rows)
+
+
+def evaluate(cases: Iterable[GoldCase], predict: Predict, match: Match) -> EvaluationReport:
+    """cases마다 predict(text, now)를 실행하고 match(예측, 정답)로 값을 비교합니다."""
+    results = tuple(_run_case(case, predict, match) for case in cases)
+    overall = Metrics()
+    by_category: dict[str, Metrics] = {}
+    for result in results:
+        overall = overall.add(result)
+        by_category = {
+            **by_category,
+            result.case.category: by_category.get(result.case.category, Metrics()).add(result),
+        }
+    return EvaluationReport(results=results, overall=overall, by_category=by_category)
+
+
+def _run_case(case: GoldCase, predict: Predict, match: Match) -> CaseResult:
+    try:
+        predicted = predict(case.text, case.now)
+    except Exception as error:  # 한 케이스의 예외가 전체 평가를 멈추지 않도록 실패로 기록
+        return CaseResult(case, None, False, f"예외 {type(error).__name__}: {error}")
+    if case.expected is None:
+        ok = predicted is None
+        return CaseResult(
+            case, predicted, ok, "" if ok else f"인식하지 않아야 함, 예측={_describe(predicted)}"
+        )
+    if predicted is None:
+        return CaseResult(case, None, False, f"인식 실패, 정답={dict(case.expected)}")
+    ok = match(predicted, case.expected)
+    return CaseResult(
+        case, predicted, ok, "" if ok else f"예측={_describe(predicted)} 정답={dict(case.expected)}"
+    )
+
+
+def _describe(prediction: Prediction | None) -> str:
+    if prediction is None:
+        return "없음"
+    to_dict = getattr(prediction, "to_dict", None)
+    return str(to_dict()) if callable(to_dict) else f"{prediction.text!r}={prediction.value!r}"
+
+
+def load_gold(path: str | Path) -> list[GoldCase]:
+    """JSONL 정답셋을 읽습니다. 형식 오류는 줄 번호와 함께 ValueError로 알립니다."""
+    default_now: datetime | None = None
+    cases: list[GoldCase] = []
+    lines = Path(path).read_text(encoding="utf-8").splitlines()
+    for number, line in enumerate(lines, start=1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+            if "_meta" in row:
+                default_now = datetime.fromisoformat(row["_meta"]["now"])
+                continue
+            cases.append(_to_case(row, default_now))
+        except (KeyError, TypeError, ValueError) as error:
+            raise ValueError(f"{path}:{number} 정답셋 형식 오류: {error}") from error
+    return cases
+
+
+def _to_case(row: Mapping[str, Any], default_now: datetime | None) -> GoldCase:
+    now = datetime.fromisoformat(row["now"]) if "now" in row else default_now
+    if now is None:
+        raise ValueError("now가 없습니다 (_meta.now 또는 케이스의 now 필요)")
+    expected = row["expected"]
+    if expected is not None and not isinstance(expected, Mapping):
+        raise TypeError("expected는 객체 또는 null이어야 합니다")
+    return GoldCase(
+        text=str(row["text"]), expected=expected, category=str(row.get("category", "default")), now=now
+    )
+
+
+__all__: Sequence[str] = ["CaseResult", "EvaluationReport", "GoldCase", "Metrics", "evaluate", "load_gold"]

korean_datetime/core/numerals.py

@@ -0,0 +1,92 @@
+"""한글 수사 파서 (한자어 수사 '이십삼', 고유어 수사 '스물세')
+
+정규식 조각(SINO, NATIVE)은 다른 규칙에 끼워 넣어 쓰고, 매칭된 문자열은 parse_* 함수로 정수로 바꿉니다.
+목록을 나열하지 않고 구조로 파싱하므로 '열한시 십오분', '삼십일일' 같은 조합도 정확히 처리합니다.
+"""
+
+from __future__ import annotations
+
+import re
+
+_SINO_DIGITS = {"일": 1, "이": 2, "삼": 3, "사": 4, "오": 5, "육": 6, "칠": 7, "팔": 8, "구": 9}
+_SINO_BODY = "(?:[이삼사오육칠팔구]?백)?(?:[이삼사오육칠팔구]?십)?[일이삼사오육칠팔구]?"
+# 1~999. lookahead로 빈 문자열 매칭을 막는다.
+SINO = f"(?=[일이삼사오육칠팔구십백]){_SINO_BODY}"
+
+_NATIVE_UNITS = {
+    "하나": 1,
+    "한": 1,
+    "둘": 2,
+    "두": 2,
+    "셋": 3,
+    "세": 3,
+    "석": 3,
+    "넷": 4,
+    "네": 4,
+    "넉": 4,
+    "다섯": 5,
+    "여섯": 6,
+    "일곱": 7,
+    "여덟": 8,
+    "아홉": 9,
+}
+_NATIVE_TENS = {
+    "열": 10,
+    "스물": 20,
+    "서른": 30,
+    "마흔": 40,
+    "쉰": 50,
+    "예순": 60,
+    "일흔": 70,
+    "여든": 80,
+    "아흔": 90,
+}
+_TENS_ALT = "|".join(sorted(_NATIVE_TENS, key=len, reverse=True))
+_UNITS_ALT = "|".join(sorted(_NATIVE_UNITS, key=len, reverse=True))
+# 1~99. '스무'는 단위명사 앞에서만 쓰는 20.
+NATIVE = f"(?:(?:{_TENS_ALT})(?:\\s?(?:{_UNITS_ALT}))?|스무|(?:{_UNITS_ALT}))"
+
+_SINO_FULL = re.compile(SINO)
+_NATIVE_FULL = re.compile(
+    f"(?:(?P<tens>{_TENS_ALT})\\s?(?P<unit>{_UNITS_ALT})?|(?P<twenty>스무)|(?P<only>{_UNITS_ALT}))"
+)
+
+
+def parse_sino(text: str) -> int | None:
+    """한자어 수사를 정수로 바꿉니다. 형식이 틀리면 None ('십십', '일일')."""
+    if not text or _SINO_FULL.fullmatch(text) is None:
+        return None
+    total, current = 0, 0
+    for char in text:
+        if char == "백":
+            total, current = total + (current or 1) * 100, 0
+        elif char == "십":
+            total, current = total + (current or 1) * 10, 0
+        else:
+            current = _SINO_DIGITS[char]
+    return total + current
+
+
+def parse_native(text: str) -> int | None:
+    """고유어 수사를 정수로 바꿉니다. 형식이 틀리면 None ('하나둘')."""
+    match = _NATIVE_FULL.fullmatch(text.strip()) if text else None
+    if match is None:
+        return None
+    if match["twenty"]:
+        return 20
+    if match["only"]:
+        return _NATIVE_UNITS[match["only"]]
+    return _NATIVE_TENS[match["tens"]] + (_NATIVE_UNITS[match["unit"]] if match["unit"] else 0)
+
+
+def parse_korean_number(text: str) -> int | None:
+    """아라비아 숫자, 한자어 수사, 고유어 수사 중 무엇이든 정수로 바꿉니다."""
+    stripped = text.strip()
+    if stripped.isdecimal():
+        return int(stripped)
+    sino = parse_sino(stripped)
+    return sino if sino is not None else parse_native(stripped)
+
+
+def syllable_count(text: str) -> int:
+    return sum(1 for char in text if not char.isspace())

korean_datetime/core/scanner.py

@@ -0,0 +1,195 @@
+"""정규식 규칙 기반 토큰 스캐너 (한국어 단어 경계·조사 인식)
+
+날짜·시간 규칙이 쓰는 저수준 엔진입니다. 규칙(TokenRule) 목록을 받아 텍스트를
+왼쪽부터 훑으며, 각 위치에서 **가장 긴 매칭**(동률이면 먼저 등록된 규칙)을 토큰으로 채택합니다.
+
+경계 규칙:
+- 왼쪽: 한글로 시작하는 매칭은 앞 글자가 한글이면 거부합니다(단, 직전 토큰이 끝난 자리는 허용).
+  "그내일"의 "내일"은 거부, "오늘저녁"의 "저녁"은 허용됩니다.
+- 오른쪽(right_boundary=True인 규칙만): 뒤에 한글이 이어지면 조사이거나 다른 토큰의 시작이어야 합니다.
+  "오일에"는 허용, "오일교환"은 거부됩니다.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+PARTICLES: tuple[str, ...] = (
+    "에서",
+    "에게",
+    "에는",
+    "에도",
+    "에",
+    "엔",
+    "의",
+    "쯤",
+    "경",
+    "께",
+    "즈음",
+    "부터",
+    "까지",
+    "이나",
+    "나",
+    "은",
+    "는",
+    "이",
+    "가",
+    "도",
+    "로",
+    "으로",
+    "만",
+    "요",
+    "이요",
+    "야",
+    "이야",
+    "랑",
+    "이랑",
+    "하고",
+    # 비교·한정·서술 ('어제만큼', '내일부턴', '오늘부터다')
+    "만큼",
+    "부턴",
+    "까진",
+    "보단",
+    "처럼",
+    "이다",
+    "다",
+    # 비교 기준으로 붙는 말 ('전년대비', '전년동기', '전월비')
+    "대비",
+    "동기",
+    "동월",
+    "동기간",
+    "비",
+    "과",
+    "와",
+    "인",
+    "이서",
+    "을",
+    "를",
+    "처럼",
+    "보다",
+    "마다",
+    "씩",
+    "이면",
+    "면",
+    "이라",
+    "라",
+    "이에요",
+    "예요",
+    "입니다",
+)
+_PARTICLE_RUN = re.compile("(?:" + "|".join(sorted(PARTICLES, key=len, reverse=True)) + ")*(?![가-힣])")
+
+
+def is_hangul(char: str) -> bool:
+    return "가" <= char <= "힣"
+
+
+def ends_word(text: str, end: int) -> bool:
+    """end 위치가 단어의 끝인지: 문장 끝, 한글이 아님, 또는 조사만 이어짐 ('서울에서' ○, '서울시' ×)"""
+    return end >= len(text) or not is_hangul(text[end]) or _PARTICLE_RUN.match(text, end) is not None
+
+
+@dataclass(frozen=True, slots=True)
+class Token:
+    """스캐너가 만든 토큰. value는 규칙의 builder가 결정합니다."""
+
+    kind: str
+    value: Any
+    start: int
+    end: int
+    text: str
+    weak: bool = False
+
+
+class Split(tuple[Token, ...]):
+    """builder가 하나의 매칭을 여러 토큰으로 나눠 내보낼 때 반환합니다 (예: '다음주말' → 주 + 주말)."""
+
+    __slots__ = ()
+
+
+Builder = Callable[["re.Match[str]"], Any]
+
+
+@dataclass(frozen=True, slots=True)
+class TokenRule:
+    """
+    Attributes:
+        kind: 토큰 종류
+        pattern: 현재 위치에서 match()로 시도할 정규식
+        build: 매칭 → 토큰 값. None을 반환하면 매칭을 거부하고, Split을 반환하면 그 토큰들을 그대로 사용
+        right_boundary: True면 오른쪽 경계 규칙을 적용
+        weak: 문맥이 있어야 의미가 있는 토큰 표시 (해석 단계에서 사용)
+        attachable: True면 앞말에 붙어 있어도 매칭 (왼쪽 경계 예외). 패턴 자체가 충분히 구별될 때만
+    """
+
+    kind: str
+    pattern: re.Pattern[str]
+    build: Builder
+    right_boundary: bool = False
+    weak: bool = False
+    attachable: bool = False
+
+
+class Scanner:
+    """TokenRule 목록으로 텍스트를 토큰화합니다. 규칙이 불변이므로 인스턴스를 재사용해도 안전합니다."""
+
+    def __init__(self, rules: Iterable[TokenRule]) -> None:
+        self._rules: tuple[TokenRule, ...] = tuple(rules)
+        if not all(isinstance(rule, TokenRule) for rule in self._rules):
+            raise TypeError("rules에는 TokenRule만 넣을 수 있습니다")
+        self._has_attachable = any(rule.attachable for rule in self._rules)
+
+    @property
+    def rules(self) -> tuple[TokenRule, ...]:
+        return self._rules
+
+    def scan(self, text: str) -> list[Token]:
+        tokens: list[Token] = []
+        pos, last_end = 0, 0
+        while pos < len(text):
+            attached = not self._left_ok(text, pos, last_end)
+            if attached and not self._has_attachable:
+                pos += 1
+                continue
+            best = self._best_match(text, pos, attached)
+            if best is None:
+                pos += 1
+                continue
+            tokens.extend(best)
+            pos = last_end = best[-1].end
+        return tokens
+
+    def _best_match(self, text: str, pos: int, attached: bool = False) -> Sequence[Token] | None:
+        """attached: 앞말에 붙은 위치라 attachable 규칙만 시도"""
+        best: Sequence[Token] | None = None
+        best_end = pos
+        for rule in self._rules:
+            if attached and not rule.attachable:
+                continue
+            match = rule.pattern.match(text, pos)
+            if match is None or match.end() <= best_end:
+                continue
+            if rule.right_boundary and not self._right_ok(text, match.end()):
+                continue
+            value = rule.build(match)
+            if value is None:
+                continue
+            best = value if isinstance(value, Split) else (self._token(rule, match, value),)
+            best_end = match.end()
+        return best
+
+    @staticmethod
+    def _token(rule: TokenRule, match: re.Match[str], value: Any) -> Token:
+        return Token(rule.kind, value, match.start(), match.end(), match.group(), rule.weak)
+
+    @staticmethod
+    def _left_ok(text: str, pos: int, last_end: int) -> bool:
+        if pos == 0 or pos == last_end or not is_hangul(text[pos]):
+            return True
+        return not is_hangul(text[pos - 1])
+
+    def _right_ok(self, text: str, end: int) -> bool:
+        return ends_word(text, end) or any(rule.pattern.match(text, end) for rule in self._rules)