[python] Introduce Mypy Typechecking

[hayat01sh1da]

1. Why (Purpose)

1-1. Reliability

• Static type checking catches type-related bugs at development time before they reach production
• Enforcing disallow_untyped_defs = true ensures every function signature is explicitly typed, eliminating ambiguity
• warn_return_any = true prevents unintentionally returning loosely-typed values, reducing runtime surprises

1-2. Maintainability

• Type annotations serve as living documentation, clarifying expected inputs/outputs for each function and method
• Explicit parameter and return types make it easier for future contributors to understand and modify code confidently
• CI-integrated typechecking guarantees type correctness is maintained throughout the project lifecycle

2. What (Procedures)

2-1. Target Repositories (13 repos)

#	Repository	Files Changed	Insertions	Deletions
1	botpress-accuracy-checkers	11	+35	-24
2	coding-tests	16	+60	-41
3	deep-learnings	1-9	+9-0	-7-9
4	file-cleaners	4	+31	-23
5	file-extension-converters	5	+39	-31
6	github-wiki-organisers	12	+1-2	-1-4
7	itunes-file-delimiter-replacer	5	+40	-32
8	json-data-sorters	4	+30	-20
9	natural-language-processing	7	+91	-77
10	pr-title-printers	4	+17	-9
11	template-creators	4	+32	-24
12	tutorials	36	+1-3	-1-5
13	web-scrapers	14	+65	-56

2-2. Mypy Configuration (pyproject.toml)

A pyproject.toml was created (or updated if it already existed) with the following [tool.mypy] section, consistent across all 13 repositories:

[tool.mypy]
python_version = "3-14"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

• python_version — Targets Python 3-14
• warn_return_any — Warns when a function returns a value typed as Any
• warn_unused_configs — Warns about unused [tool.mypy] config entries
• disallow_untyped_defs — Rejects function definitions without type annotations (the strictest baseline)

2-3. Type Annotations Added to Source and Test Files

• Function parameters: Added type annotations to all parameters (e.g., def __init__(self, scheme: str, host: str, bot_id: str, ...) -> None:)
• Return types: Added return type annotations to all functions/methods (e.g., -> str, -> None, -> list[dict[str, Any]])
• from typing import: Used Any, TextIO, etc. from the typing module where Python built-in types were insufficient (mainly in botpress-accuracy-checkers, deep-learnings, json-data-sorters, natural-language-processing, web-scrapers)
• from __future__ import annotations: Used in coding-tests and deep-learnings for forward-compatible union type syntax (e.g., int | str)
• Test methods: All setUp(), tearDown(), and test_*() methods annotated with -> None

2-4. GitHub Actions Workflow Updates

The CI pipeline was updated to include a mypy typechecking step in the existing GHA workflow files:

1. Dependency installation — Added mypy to pip install alongside flake8 and pytest:

   pip install flake8 mypy pytest

2. Typecheck step — Inserted a new Typecheck with mypy step between flake8 linting and unit test execution:

   - name: Typecheck with mypy
     working-directory: ./python  # where applicable
     run: mypy .

   • For repos with a python/ subdirectory (most repos): working-directory: ./python was specified
   • For repos where Python is at root level (web-scrapers, deep-learnings, natural-language-processing): mypy . runs from the repo root
   • deep-learnings has 3 separate workflow files (vol1.yml, vol2.yml, vol3.yml), each updated with the mypy step

3. How (Operation and Maintenance)

3-1. Automatic Enforcement via CI

• Mypy runs on every push and pull request via GitHub Actions
• The step is placed after flake8 linting and before unit tests, so type errors are caught early in the pipeline
• Any type errors will cause the CI pipeline to fail, blocking the merge

3-2. Day-to-Day Development

• When adding new functions/methods, type annotations are required — mypy rejects untyped definitions (disallow_untyped_defs = true)
• When modifying existing function signatures, type annotations must be updated accordingly
• Run mypy . locally before pushing to catch issues early

3-3. Updating Configuration

• Mypy settings are centralised in pyproject.toml at the Python project root
• When upgrading the Python version, update python_version in pyproject.toml

4. Pros & Cons

4-1. Pros

• Early bug detection: Type mismatches are caught at static analysis time, not at runtime
• Self-documenting code: Type annotations make function contracts explicit without extra comments
• CI-enforced quality gate: Prevents type regressions from being merged
• Minimal configuration: A single 5-line [tool.mypy] block in pyproject.toml covers the entire project
• Zero runtime overhead: Mypy is a static analyser only — no performance impact on production code
• Gradual adoption: Can be introduced incrementally; existing untyped code can be annotated file by file

4-2. Cons

• Initial effort: All existing function signatures must be annotated upfront (1-9 files changed in deep-learnings alone)
• Learning curve: Developers unfamiliar with Python type hints need to learn typing module constructs (Any, TextIO, union types, etc.)
• Third-party library stubs: Some libraries lack type stubs, potentially requiring type: ignore comments or stub packages
• Increased verbosity: Type annotations add visual noise to otherwise concise Python code
• Maintenance cost: Signature changes require updating type annotations in tandem, adding friction to refactoring