Fix type hints for Python 3.9 runtime compatibility

[Copilot]

What does this changes

Fixes type hints that break Python 3.9 runtime introspection (typing.get_type_hints()). Replaces PEP 604 | union syntax with Union[]/Optional[], adds missing return type hints, and ensures from __future__ import annotations is present where needed.

Files changed: 11 files across tag, tokenize, spell, benchmarks, transliterate, coref, and word_vector modules.

What was wrong

The | union operator (PEP 604) evaluates at runtime in Python 3.9, causing failures when static analysis tools, documentation generators, or runtime type inspection call typing.get_type_hints(). For example:

# This breaks in Python 3.9 runtime type inspection
def func(x: str | None) -> dict[str, str | bool]:
    ...

Additionally, ~20 functions lacked return type hints, and one module with type hints was missing the future annotations import.

How this fixes it

Union syntax fixes (2 occurrences):

• pythainlp/tag/thainer.py: str | bool → Union[str, bool]
• pythainlp/tokenize/han_solo.py: str | None → Optional[str]

Missing imports (1 file):

• pythainlp/tokenize/__init__.py: Added from __future__ import annotations

Missing return types (8 files):

• spell/core.py: NorvigSpellChecker (with TYPE_CHECKING)
• spell/symspellpy.py: SymSpell
• tag/perceptron.py: PerceptronTagger (5 functions)
• tag/unigram.py: dict (5 functions)
• transliterate/core.py: Callable[[str], str]
• benchmarks/word_tokenization.py: np.ndarray
• coref/core.py: list[dict]
• word_vector/core.py: None

With from __future__ import annotations, type hints become strings at parse time, avoiding runtime evaluation issues while maintaining compatibility with Python 3.9.

Your checklist for this pull request

• Passed code styles and structures
• Passed code linting checks and unit test

Original prompt

Find in the code, code comments, and documentation for wrong type hints or inconsistent type hints.

Fix them all, in every submodules.
Fix one submodule at a time, review, revise, commit, then iterate to other submodules.

Keep the Python 3.9 compatibility (with import future annotations).
Do not the | union syntax as it will fail at runtime in Python 3.9 when introspection tools call typing.get_type_hints().
We need our modules to be useable by static analysis tools, documentation generators, and runtime type inspection.

Use PR #1230 as reference.

mypy, pyrefly, and pyright can be used to help find type issues but we don't have to taken care of every suggestions made by these tools at this stage. The priority now is to make all functions have type hints and have them in a consistent way.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coveralls]

coverage: 53.665% (+0.03%) from 53.632%
when pulling b93128a on copilot/fix-type-hints-inconsistent
into 59695bd on dev.