Align docstrings with type hints across codebase by Copilot · Pull Request #1270 · PyThaiNLP/pythainlp

Copilot · 2026-02-03T12:13:04Z

What do these changes do

Synchronizes docstrings with type hints, eliminating 42 mismatches where documentation used outdated typing module syntax while code used Python 3.9+ native types. Additionally ensures non-standard types use fully qualified module names for clarity.

What was wrong

Docstrings documented types as List[str], Dict[...], Tuple[...] (typing module style) while function signatures used list[str], dict[...], tuple[...] (native Python 3.9+ style). Additionally, some docstrings used local import aliases (like pd.DataFrame) or unqualified type names (like Word2VecKeyedVectors) instead of fully qualified module names, making it unclear which module provides the type.

How this fixes it

Documentation updates (42 fixes across 16 files):

List → list, Dict → dict, Tuple → tuple in :rtype: annotations
Union[List[...], ...] → Union[list[...], ...] for consistency
Non-standard types now use fully qualified names:
- pd.DataFrame → pandas.DataFrame
- Word2VecKeyedVectors → gensim.models.keyedvectors.Word2VecKeyedVectors
- ndarray → numpy.ndarray

Type hint improvements (3 instances):

dict → dict[str, Any] in benchmarks/word_tokenization.py for flattened result structures
list → list[tuple[int, int]] where docstrings specified structure

High-impact modules:

tokenize/core.py: 8 fixes (tokenization return types)
benchmarks/word_tokenization.py: 8 fixes (benchmark metrics)
phayathaibert/core.py: 4 fixes (NER outputs)
word_vector/core.py: 4 fixes (word vector model types)

Your checklist for this pull request

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

Original prompt

Verify precision of type hints and annotations and docstring.

Current codebase contains some type hints and comments for static type checkers,
including ones that added by these PRs:

#1262
#1263
#1264
#1265
#1266
#1267
#1268
#1269

With the scope of the entire package (100%), incrementally verify if the annotations are correct and precise, and if the docstring and other documentation are up to date to the type hints.

Goals

When a type hint exist, it is correct and the docstring is correct

Use "ignore" comments only when it is necessary and with a scoped/specific type

Report percentage of type hints coverage of the entire package

Instructions

Follow best practices and standard Python type hint patterns.

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

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

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

Co-authored-by: bact <128572+bact@users.noreply.github.com>

…oint None check Co-authored-by: bact <128572+bact@users.noreply.github.com>

… code Co-authored-by: bact <128572+bact@users.noreply.github.com>

coveralls · 2026-02-03T12:33:30Z

coverage: 65.571% (-0.08%) from 65.653%
when pulling c656076 on copilot/verify-type-hints-annotations
into a248ba9 on dev.

Update docstrings to use native Python types (list, dict, tuple) instead of typing module style (List, Dict, Tuple) to match the type hints. This affects: - pythainlp/phayathaibert/core.py (4 fixes) - pythainlp/benchmarks/word_tokenization.py (4 fixes) - pythainlp/word_vector/core.py (2 fixes) - pythainlp/tag/named_entity.py (2 fixes) - pythainlp/spell/core.py (2 fixes) - pythainlp/tag/tltk.py (1 fix) - pythainlp/tag/thainer.py (1 fix) - pythainlp/tag/chunk.py (1 fix) - pythainlp/spell/words_spelling_correction.py (1 fix) - pythainlp/spell/pn.py (1 fix) - pythainlp/coref/core.py (1 fix) Co-authored-by: bact <128572+bact@users.noreply.github.com>

Co-authored-by: bact <128572+bact@users.noreply.github.com>

bact · 2026-02-03T13:26:50Z


    :return: dataframe with row x col = len(samples) x len(metrics)
-    :rtype: pandas.DataFrame
+    :rtype: pd.DataFrame


keep the fullname. "pd" is an alias used only locally.

Fixed in c656076 - changed to pandas.DataFrame

bact · 2026-02-03T13:28:26Z


        :return: `gensim` word2vec model
-        :rtype: gensim.models.keyedvectors.Word2VecKeyedVectors
+        :rtype: Word2VecKeyedVectors


Use fullname of the imported.

Fixed in c656076 - changed to gensim.models.keyedvectors.Word2VecKeyedVectors

bact · 2026-02-03T13:29:01Z

        :return: 300-dimension vector representing the given sentence
                 in form of :mod:`numpy` array
-        :rtype: :class:`numpy.ndarray((1,300))`
+        :rtype: ndarray


use full qualified name "numpy.ndarray"

Fixed in c656076 - changed to numpy.ndarray

bact

@copilot in docstring, for the non-standard types, use full qualified name. So the user can know that the type comes from which module.

Co-authored-by: bact <128572+bact@users.noreply.github.com>

sonarqubecloud · 2026-02-03T13:33:12Z

Quality Gate failed

Failed conditions
17.3% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud

Initial plan

a23b229

Copilot AI assigned Copilot and bact Feb 3, 2026

Copilot started work on behalf of bact February 3, 2026 12:13 View session

Fix mypy type errors - remove unused type: ignore comments

39ea5a7

Co-authored-by: bact <128572+bact@users.noreply.github.com>

bact added this to PyThaiNLP Feb 3, 2026

bact added the refactoring a technical improvement which does not add any new features or change existing features. label Feb 3, 2026

bact added this to the 5.3 milestone Feb 3, 2026

Copilot AI and others added 2 commits February 3, 2026 12:22

Add proper type: ignore comments for numpy Any returns and fix checkp…

ad78216

…oint None check Co-authored-by: bact <128572+bact@users.noreply.github.com>

Replace assert statements with proper exception raising in production…

629d216

… code Co-authored-by: bact <128572+bact@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Verify precision of type hints and docstrings~~ Verify and improve type hints precision across codebase Feb 3, 2026

Copilot AI requested a review from bact February 3, 2026 12:29

Copilot finished work on behalf of bact February 3, 2026 12:29

bact approved these changes Feb 3, 2026

View reviewed changes

bact marked this pull request as ready for review February 3, 2026 13:04

Copilot started work on behalf of bact February 3, 2026 13:05 View session

Copilot AI and others added 3 commits February 3, 2026 13:10

Fix typo: boundareies -> boundaries in docstring

3a669cf

Co-authored-by: bact <128572+bact@users.noreply.github.com>

Update docstrings to match type hints - use native types

9778e5e

Co-authored-by: bact <128572+bact@users.noreply.github.com>

Copilot AI changed the title ~~Verify and improve type hints precision across codebase~~ Align docstrings with type hints across codebase Feb 3, 2026

Copilot AI requested a review from bact February 3, 2026 13:21

Copilot finished work on behalf of bact February 3, 2026 13:21

bact reviewed Feb 3, 2026

View reviewed changes

Copilot started work on behalf of bact February 3, 2026 13:30 View session

Use fully qualified names for non-standard types in docstrings

c656076

Co-authored-by: bact <128572+bact@users.noreply.github.com>

Copilot AI requested a review from bact February 3, 2026 13:32

Copilot finished work on behalf of bact February 3, 2026 13:32

bact approved these changes Feb 3, 2026

View reviewed changes

bact merged commit e9b8f3b into dev Feb 3, 2026
20 of 31 checks passed

bact deleted the copilot/verify-type-hints-annotations branch February 3, 2026 13:38

github-project-automation Bot moved this to Done in PyThaiNLP Feb 3, 2026

bact linked an issue Mar 2, 2026 that may be closed by this pull request

Incompatible types in benchmarks.word_tokenization #1030

Closed

bact mentioned this pull request Mar 2, 2026

Incompatible types in benchmarks.word_tokenization #1030

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Align docstrings with type hints across codebase - #1270

Align docstrings with type hints across codebase#1270
bact merged 8 commits into
devfrom
copilot/verify-type-hints-annotations

Copilot AI commented Feb 3, 2026 •

edited

Loading

Uh oh!

coveralls commented Feb 3, 2026 •

edited

Loading

Uh oh!

bact Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

bact Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

bact Feb 3, 2026

Uh oh!

Copilot AI Feb 3, 2026

Uh oh!

bact left a comment

Uh oh!

sonarqubecloud Bot commented Feb 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

Copilot AI commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What do these changes do

What was wrong

How this fixes it

Your checklist for this pull request

Goals

Instructions

Uh oh!

coveralls commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bact Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

bact Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

bact Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

bact left a comment

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud Bot commented Feb 3, 2026

Quality Gate failed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 3, 2026 •

edited

Loading

coveralls commented Feb 3, 2026 •

edited

Loading