- Home
- Skills
- Code Quality & Review
- Python Type Checking Adoption with mypy or Pyright
Works with the AI Agents you already use
Python Type Checking Adoption with mypy or Pyright
Add mypy or Pyright to a legacy Python codebase step by step: baseline, per-module strictness ladder, real bugs fixed, type-ignore debt counted, CI ratchet. TYPED / PARTIAL / UNTYPED.
$5
Python Type Checking Adoption with mypy or Pyright
Example session with this skill installed
Our Django + Celery app (about 60k lines, Python 3.12) has no type checking. Set up mypy so we can adopt it gradually, fix any real bugs it finds, and add a CI gate that stops it getting worse.
- Read your context and instructions
- Compiled the python type checking
Typing report: logistics-api (2026-10-19)
Verdict: PARTIAL (was UNTYPED) - CI gate and ratchet active; 4 of 11 packages at rung 2 or higher.
Checker: mypy 1.x pinned in dev deps, Python 3.12, plugins: django-stubs (mypy_django_plugin), celery-types.
Baseline -> now (measured)
| Metric | Baseline | Now |
|---|---|---|
| errors (default checks) | 1,312 | 641 |
| type: ignore count | 0 | 23 (each with an error code and reason) |
| fully annotated functions | 18% | 41% |
Module ladder
| Package | Before | Now | Notes |
|---|---|---|---|
| core/money | 0 | 3 (strict) | Decimal-only arithmetic now enforced |
| core/models | 0 | 2 | TypedDicts for JSON fields |
| shipments/services | 0 | 2 | |
| integrations/carriers | 0 | 2 | Protocol for carrier clients |
| api/views | 0 | 1 | DRF serializers next |
| tasks (Celery) | 0 | 1 | |
| legacy/reports | 0 | 0 | ignore_errors override, owner: data team |
| 4 others | 0 | 1 |
Real bugs found (separate commits, each with a test)
| file:line | Bug | Test |
|---|---|---|
| shipments/services.py:88 | get_rate() returns None for unknown zones, caller multiplies it -> TypeError in production logs | test_unknown_zone_rate |
| core/money.py:41 | float added to Decimal in discount path, rounding drift | test_discount_decimal |
| tasks/notify.py:17 | wrong kwarg name recipient vs recipients, silently ignored by **kwargs passthrough | test_notify_kwargs |
Changes
pyproject.toml: [tool.mypy] with warn_unused_ignores, per-module overrides for the ladder- Stubs added: django-stubs, celery-types, types-requests, types-redis
.type-baseline.json+ CI job:mypy . > mypy.txt; python scripts/type_ratchet.py --tool mypy --output mypy.txt- Annotation-only commits: 37 files; test suite unchanged and passing (measured)
Next 3 modules to promote
- api/views to rung 2 (DRF serializer types)
- tasks to rung 2
- core/models to strict
Connects securely to your tools. The creator never sees your data.
About this skill
You want the safety of static types in your Python codebase, but turning on mypy --strict produces 4,000 errors, and the last attempt ended with a config full of ignore_errors = true that nobody looks at. Asking an AI to "add type hints" usually produces a giant diff of guessed annotations, sprinkled with Any and cast(), that changes nothing real.
This skill gives your coding agent a gradual, measured adoption plan, a checker guide and a bundled ratchet script. It:
- Assesses Python versions, project type (app vs published library), frameworks (Django, Pydantic, SQLAlchemy 2.x, FastAPI, Celery, attrs) and any existing checker config
- Chooses one checker as the CI gate (mypy, or Pyright/basedpyright) with the reason stated
- Records a baseline: total errors, errors by code and by package, and type-ignore count, using the bundled type_ratchet.py (or basedpyright's baseline file)
- Installs missing stubs and scopes ignore_missing_imports per package, never globally
- Promotes modules one at a time up a strictness ladder (not checked -> default -> no untyped defs -> strict), leaf modules and core models first
- Fixes the real bugs the checker finds (usually None handling) in separate commits, each with a test
- Uses precise types (TypedDict, Protocol, Literal, overload, TypeIs) instead of Any and cast
- For libraries: adds py.typed and checks public API completeness with pyright --verifytypes
- Adds a CI job that fails if errors or ignores go up, so the codebase only gets stricter
- Gives a verdict: TYPED, PARTIAL or UNTYPED, with a module ladder table and the next three modules to promote
For Python teams adopting types in a legacy app, a Django or FastAPI service, a data pipeline or an open-source library.
Honesty note: annotation-only changes must not change behaviour, and any behaviour change is called out as a bug fix with a test. Every number in the report comes from a real checker run, or is marked "not measured". It does not silence errors globally to get a green build.
Highly dynamic code may remain at a low strictness rung with documented ignores. Packages without stubs need minimal local stubs. Results depend on the pinned checker version.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 28 days ago
Requires