Rename Stats→Stat (singular) and global→global_ in TokenizationStat

- CharLevelStats → CharLevelStat (singular, matches BleuScore/RougeScore)
- WordLevelStats → WordLevelStat
- GlobalStats → GlobalStat
- TokenizationStats → TokenizationStat; converted from functional TypedDict
  form to class form now that global_ is a valid identifier
- "global" key → "global_" in compute_stats() return value
- Update __init__.py __all__ and imports
- Update tests: import names, assertIn("global_"), typed annotations
- Update CHANGELOG migration notes

Co-authored-by: bact <128572+bact@users.noreply.github.com>
Agent-Logs-Url: https://github.com/PyThaiNLP/pythainlp/sessions/d0fa4ca1-06a6-48cc-b353-4df24554e700

Author: Copilot

CHANGELOG.md

@@ -35,19 +35,21 @@ and this project adheres to
   fmeasure   = scores["rouge1"]["fmeasure"]
   ```
 
-- `CharLevelStats`, `WordLevelStats`, `GlobalStats`, and `TokenizationStats`
+- `CharLevelStat`, `WordLevelStat`, `GlobalStat`, and `TokenizationStat`
   TypedDicts in `pythainlp.benchmarks`: give named, type-safe access to the
-  dict returned by `word_tokenization.compute_stats()`.
+  dict returned by `word_tokenization.compute_stats()`. The global-level key
+  is `"global_"` (trailing underscore avoids the Python reserved word).
 
   ```python
   # Before (opaque nested dict)
   result = compute_stats(ref, hyp)
   tp = result["char_level"]["tp"]
 
-  # After (same access, now type-safe with TokenizationStats)
-  from pythainlp.benchmarks import TokenizationStats
-  result: TokenizationStats = compute_stats(ref, hyp)
+  # After (same access, now type-safe with TokenizationStat)
+  from pythainlp.benchmarks import TokenizationStat
+  result: TokenizationStat = compute_stats(ref, hyp)
   tp = result["char_level"]["tp"]
+  indicators = result["global_"]["tokenisation_indicators"]
   ```
 
 - `CorefResult` TypedDict is now exported from `pythainlp.coref`.

pythainlp/benchmarks/__init__.py

@@ -5,11 +5,11 @@
 
 __all__: list[str] = [
     "BleuScore",
-    "CharLevelStats",
-    "GlobalStats",
+    "CharLevelStat",
+    "GlobalStat",
     "RougeScore",
-    "TokenizationStats",
-    "WordLevelStats",
+    "TokenizationStat",
+    "WordLevelStat",
     "benchmark",
     "bleu_score",
     "character_error_rate",
@@ -26,9 +26,9 @@
     word_error_rate,
 )
 from pythainlp.benchmarks.word_tokenization import (
-    CharLevelStats,
-    GlobalStats,
-    TokenizationStats,
-    WordLevelStats,
+    CharLevelStat,
+    GlobalStat,
+    TokenizationStat,
+    WordLevelStat,
     benchmark,
 )

pythainlp/benchmarks/word_tokenization.py

@@ -30,7 +30,7 @@
 TAILING_SEP_RX: re.Pattern[str] = re.compile(f"{re.escape(SEPARATOR)}$")
 
 
-class CharLevelStats(TypedDict):
+class CharLevelStat(TypedDict):
     """Character-level confusion matrix statistics for tokenization."""
 
     tp: int
@@ -39,30 +39,26 @@ class CharLevelStats(TypedDict):
     fn: int
 
 
-class WordLevelStats(TypedDict):
+class WordLevelStat(TypedDict):
     """Word-level tokenization statistics."""
 
     correctly_tokenised_words: int
     total_words_in_sample: int
     total_words_in_ref_sample: int
 
 
-class GlobalStats(TypedDict):
-    """Global tokenization indicators as a binary indicator string."""
+class GlobalStat(TypedDict):
+    """Global tokenization indicator as a binary indicator string."""
 
     tokenisation_indicators: str
 
 
-# Functional form is required because 'global' is a Python reserved keyword.
-TokenizationStats = TypedDict(
-    "TokenizationStats",
-    {
-        "char_level": CharLevelStats,
-        "word_level": WordLevelStats,
-        "global": GlobalStats,
-    },
-)
-"""Tokenization quality statistics at character, word, and global level."""
+class TokenizationStat(TypedDict):
+    """Tokenization quality statistics at character, word, and global level."""
+
+    char_level: CharLevelStat
+    word_level: WordLevelStat
+    global_: GlobalStat
 
 
 def _f1(precision: float, recall: float) -> float:
@@ -81,7 +77,7 @@ def _f1(precision: float, recall: float) -> float:
 
 @overload
 def _flatten_result(
-    my_dict: TokenizationStats, sep: str = ...
+    my_dict: TokenizationStat, sep: str = ...
 ) -> dict[str, Union[int, str]]: ...
 
 
@@ -105,7 +101,7 @@ def _flatten_result(
 
 
     :param my_dict: dictionary containing stats
-    :type my_dict: TokenizationStats or
+    :type my_dict: TokenizationStat or
         collections.abc.Mapping[str, collections.abc.Mapping[str, Union[int, str]]]
     :param str sep: separator between the two keys (default: ":")
 
@@ -189,7 +185,7 @@ def preprocessing(txt: str, remove_space: bool = True) -> str:
 
 def compute_stats(
     ref_sample: str, raw_sample: str
-) -> TokenizationStats:
+) -> TokenizationStat:
     """Compute statistics for tokenization quality
 
     These statistics include:
@@ -206,7 +202,7 @@ def compute_stats(
     :param str samples: samples that we want to evaluate
 
     :return: metrics at character- and word-level and indicators of correctly tokenized words
-    :rtype: TokenizationStats
+    :rtype: TokenizationStat
     """
     import numpy as np
 
@@ -244,18 +240,18 @@ def compute_stats(
     tokenization_indicators_str = list(map(str, tokenization_indicators))
 
     return {
-        "char_level": CharLevelStats(
+        "char_level": CharLevelStat(
             tp=c_tp,
             fp=c_fp,
             tn=c_tn,
             fn=c_fn,
         ),
-        "word_level": WordLevelStats(
+        "word_level": WordLevelStat(
             correctly_tokenised_words=correctly_tokenised_words,
             total_words_in_sample=int(np.sum(sample_arr)),
             total_words_in_ref_sample=int(np.sum(ref_sample_arr)),
         ),
-        "global": GlobalStats(
+        "global_": GlobalStat(
             tokenisation_indicators="".join(tokenization_indicators_str),
         ),
     }

tests/extra/testx_benchmarks.py

@@ -9,11 +9,11 @@
 
 from pythainlp.benchmarks import (
     BleuScore,
-    CharLevelStats,
-    GlobalStats,
+    CharLevelStat,
+    GlobalStat,
     RougeScore,
-    TokenizationStats,
-    WordLevelStats,
+    TokenizationStat,
+    WordLevelStat,
     bleu_score,
     rouge_score,
     word_tokenization,
@@ -59,31 +59,31 @@ def test_compute_stats(self):
             self.assertIsNotNone(result)
 
     def test_compute_stats_return_type(self):
-        """Test that compute_stats returns a TokenizationStats typed dict."""
+        """Test that compute_stats returns a TokenizationStat typed dict."""
         ref = word_tokenization.preprocessing("อากาศ|ร้อน|มาก")
         act = word_tokenization.preprocessing("อากาศ|ร้อนมาก")
 
-        result: TokenizationStats = word_tokenization.compute_stats(ref, act)
+        result: TokenizationStat = word_tokenization.compute_stats(ref, act)
 
         self.assertIsInstance(result, dict)
         self.assertIn("char_level", result)
         self.assertIn("word_level", result)
-        self.assertIn("global", result)
+        self.assertIn("global_", result)
 
-        char: CharLevelStats = result["char_level"]
+        char: CharLevelStat = result["char_level"]
         self.assertIsInstance(char, dict)
         self.assertIsInstance(char["tp"], int)
         self.assertIsInstance(char["fp"], int)
         self.assertIsInstance(char["tn"], int)
         self.assertIsInstance(char["fn"], int)
 
-        word: WordLevelStats = result["word_level"]
+        word: WordLevelStat = result["word_level"]
         self.assertIsInstance(word, dict)
         self.assertIsInstance(word["correctly_tokenised_words"], int)
         self.assertIsInstance(word["total_words_in_sample"], int)
         self.assertIsInstance(word["total_words_in_ref_sample"], int)
 
-        glob: GlobalStats = result["global"]
+        glob: GlobalStat = result["global_"]
         self.assertIsInstance(glob, dict)
         self.assertIsInstance(glob["tokenisation_indicators"], str)