Iterating to incrementally complete type annotations to reach 100% coverage of the entire codebase.

Strategy

• Plan and break work into smaller batches, based on
  type analysis data generated from
  https://github.com/PyThaiNLP/pythainlp/blob/dev/build_tools/analysis/type_hint_analyzer.py
  The data tells which submodules have functions/classes/etc
  with high priority waiting to get annotations complete
  and where is the file.
  (Mind that the script may not very hight accurate. But it is usable as a map)
• Moving gradually one by one
• After each commit, regenerate the type analysis data
  to see where to go next
• Keep iterate until reach 100% coverage
• See these PRs and their comments for previous
  works on adding type annotations:
  Complete type annotations: 100% functions, 56.56% variables, eliminate 25+ Any types #1272
  Fix lazy import bugs and Python 3.9 type hint compatibility #1274
  Align docstrings with type hints across codebase #1270

Goals

• Reach 100% type completeness in the entire repo,
  make the package a typed package, while keeping maintainability.
• All functions, methods, variables, classes, type aliases, decorators, have proper annotation of known type, according to https://typing.python.org/en/latest/guides/libraries.html#type-completeness

Instructions

• Follow best practices and standard Python type hint patterns.
• Maintain source code readability.
• Use mypy as main assistant.
  • mypy is already in "dev" extra dependencies in pyproject.toml
  • mypy configuration is in pyproject.toml
  • Sometimes mypy may report errors wrongly due to cache issues. Try to reset the cache.
• Use pyright, pyrefly, and pytype for second opinions.
• Required dependencies for each test suite are in pyproject.toml. Install them to avoid errors. See https://github.com/PyThaiNLP/pythainlp/blob/dev/tests/README.md
• Use native type in type hint (list, tuple, .. instead of List, Tuple, ..)
• Do not use A | B style Union, use full Union[] instead.
• We want to keep compatibility with Python 3.9 strict and allow type inspection tools to work correctly.
• When insert typing imports, put it in appropriate location and order
• Use "if TYPE_CHECKING import" block when possible.
• When reordering the imports, beware of circular import. Read comments near imports to get more information.
• Remove unused imports
• Do not allow the use of assert in production code (it is only allowed for testing and debugging).
• Try to fix the type, the scope logic, or do the casting, before putting #type: ignore comment.
• When dealing with types from external libraries:
  • Check if type information is provided (maybe through stubs). If it is, cast wrapper may not necessary.
  • If return type is not provided, may be it is appropriate to use # type: ignore[no-any-return] annotation for clarity.
  • Analyse source code of external libraries to validate correct types
• Minimize the use of Any
  There can be a more precise type to use if we
  look at the source code of the external library.
  See examples from these commits:
  964c1d4
  42e7df1
  c382092
  e717065
• Recheck necessity when do casting.
• Recheck necessity of # noqa: and # type: ignore
• Provide type stubs as necessary.
• After changes for type hints, recheck for functionality correctness.
• Recheck docstring and documentation consistency with the code; They should match the updated type hints.
• Recheck formatting with ruff
• Do another code review
• Address code review feedback