Add type hints to foundation submodules (tools, cli, corpus)

[Copilot]

What do these changes do

Adds comprehensive type hints to 3 of 4 foundation submodules per stage 1 goal. Establishes mypy configuration and type checking infrastructure for the codebase.

Completed modules (23 files):

• pythainlp.tools - 4 files, passes mypy strict
• pythainlp.cli - 7 files, passes mypy strict
• pythainlp.corpus - 12 files, all exported functions typed

Remaining: pythainlp.tokenize (24 files, 3360 lines) - deferred due to complexity

Infrastructure:

• Mypy configuration in pyproject.toml
• Python 3.9 compatible types (Union not |, native types, TYPE_CHECKING blocks)
• Strict checking enabled for completed foundation modules
• Optional dependency imports ignored

What was wrong

Foundation submodules lacked type hints, preventing:

• Static type checking with mypy
• IDE type inference and autocompletion
• Runtime type inspection by tools
• Path to typed package status

How this fixes it

Type hint additions:

• Function signatures: return types and parameter types
• Class attributes: proper type annotations
• Module-level variables: explicit types for collections

Patterns applied:

# Before
def get_corpus(filename, comments=True):
    return frozenset(...)

# After
def get_corpus(filename: str, comments: bool = True) -> frozenset[str]:
    return frozenset(...)

TYPE_CHECKING usage:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from collections.abc import Sequence

def func(argv: Sequence[str]) -> None: ...

Standards enforced:

• Union[A, B] for Python 3.9 (not A | B)
• Native generics: list[str] not List[str]
• Optional[T] explicit
• Specific generic parameters: frozenset[str] not frozenset

Your checklist for this pull request

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

Original prompt

Gradually add type hints to submodules. Start small in the area with high confidence, then gradually grow one submodule at a time. Use mypy as main assistant. Use pyright, pyrefly, and pytype for second opinions.

Start with highly tested submodules first.

1st stage goal - 100% type hints in "foundation" submodules, namely: pythainlp.corpus, pythainlp.tokenize, pythainlp.tools, pythainlp.cli
2nd stage goal - 100% type hints in every submodules used in "core" test suite.
3rd stage goal - 100% type hints in every submodules used in "compact" test suite.
4th stage goal - 100% type hints in every submodules used in "extra" test suite.
5th stage goal - 30% type hints in the rest of the submodules (lower expectation here because some may not have CI test) -- try to reach higher if possible.

Use Python 3.9 compatible style.
Use native type (list, tuple, etc).
Use Union (not pipe).

Try to fix the type, the scope logic, or do the casting, before putting #type: ignore comment.
Recheck necessity when do casting.

Provide stubs as necessary.
Recheck code, docstring, documentation consistency.

Ultimate goal is to make the package a typed package, while keeping maintainability.

---

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

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
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