Python Type Hints Backfiller

What this skill does

Adds type hints to a previously-untyped Python module, then proves the module passes mypy --strict without changing the project-wide mypy configuration. Each function and method gains parameter and return annotations; module-level constants gain Final annotations.

Inputs

• module_path: path to a .py file or a package directory.
• repo_dir: project root containing pyproject.toml or mypy.ini.
• Optional monkeytype_db: path to a MonkeyType SQLite db with runtime traces, used for hint inference.

Steps

1. Run python -c "import ast; ast.parse(open('<module_path>').read())" to confirm the file parses.
2. If monkeytype_db is provided, run monkeytype apply <module-import-path> to seed coarse hints from runtime traces.
3. For functions without traces, infer hints from defaults, type-checked usage, and pep-deconstructable patterns: def f(x=0) -> x: int, def g(items=()) -> items: tuple[Any, ...], return None if the body has no return with a value.
4. Replace from typing import List, Dict, Tuple with builtin generics (list, dict, tuple) for Python >= 3.9.
5. Add from __future__ import annotations at the top so forward references work without quoting.
6. Annotate module-level constants with Final: MAX_RETRIES: Final[int] = 3.
7. For methods, type self only if it's a generic-bound (Self from typing); otherwise omit.
8. Run mypy --strict <module_path> from repo_dir and capture errors.
9. Iterate: for each error, add or refine the annotation; never silence with # type: ignore unless the error is a known third-party stub gap, in which case add a comment with the issue link.
10. Re-run mypy until exit 0.

Output

The original module_path with annotations added in place. A sibling mypy-strict-report.md listing the count of annotations added, the count of # type: ignore exits taken (each with a reason), and the final mypy command output.

Verification

Run mypy --strict <module_path> from a clean shell and confirm exit 0 plus zero errors. Run the project's existing test suite (pytest <tests-for-module>) and confirm pass/fail counts match the pre-migration baseline. Diff the file with git diff --stat to confirm only annotations and imports changed; any logic edits are out of scope and must be reverted.

Edge cases

• Dynamic attribute access (getattr(obj, name)): annotate with Any and note in the report; refactoring is out of scope.
• Decorators that change signatures (functools.wraps is fine, but click.command mutates types): use cast at the call site if mypy complains.
• Module imports an untyped third-party library: install stubs (pip install types-<lib>) or add [[tool.mypy.overrides]] ignore in a separate PR — do not weaken project config in this skill's scope.
• Star imports (from x import *): refuse to type-hint; ask the maintainer to convert to explicit imports first.