109 lines
5.6 KiB
Markdown
109 lines
5.6 KiB
Markdown
---
|
|
name: python-typing
|
|
description: "Reference-first skill for reviewing and modernizing Python typing to the newest supported best practices. Use when auditing annotations, replacing legacy typing syntax, and enforcing latest-syntax-first conventions."
|
|
argument-hint: "Which files or package should be reviewed, and what Python baseline must be preserved?"
|
|
x-personal-mcp:
|
|
id: python-typing
|
|
version: 1.0.0
|
|
tags:
|
|
- python
|
|
- typing
|
|
- type-hints
|
|
- pep-695
|
|
- modernization
|
|
- static-analysis
|
|
capabilities:
|
|
- resource://skills/python-typing/document
|
|
depends_on: []
|
|
---
|
|
|
|
# Modern Python Typing Review Reference
|
|
|
|
Use this skill to enforce a latest-syntax-first typing standard grounded in current Python language guidance.
|
|
|
|
Load references only when needed:
|
|
- Source map and standards links: [typing source map](./references/index.md)
|
|
- Practical review workflow and quality gates: [typing review workflow](./references/review-workflow.md)
|
|
- Astral ty adoption and operation guidance: [Astral ty usage reference](./references/astral-ty.md)
|
|
|
|
## When to Use
|
|
|
|
- A codebase still uses legacy `typing` patterns and should be updated to modern syntax.
|
|
- You need a repeatable process for type-focused code review across a package or module.
|
|
- You want references to official Python docs and PEPs attached to recommendations.
|
|
- You need to decide whether a modern feature is allowed under the project Python version.
|
|
|
|
## How To Use This Skill
|
|
|
|
1. Confirm the effective Python baseline from project config (for example `pyproject.toml` and lint target version).
|
|
2. Scan target files for legacy patterns and prioritize newest canonical syntax first.
|
|
3. Apply modern typing upgrades aggressively, keeping runtime behavior stable unless explicitly requested otherwise.
|
|
4. Validate with project lint and diagnostics.
|
|
5. Report what changed and list only hard-blocker deferrals (for example incompatible Python baseline).
|
|
|
|
## Intent Router
|
|
|
|
- Baseline and compatibility checks: [typing source map](./references/index.md)
|
|
- Exact modernization sequence and branching logic: [typing review workflow](./references/review-workflow.md)
|
|
- Integrating or tuning Astral ty: [Astral ty usage reference](./references/astral-ty.md)
|
|
- Need official rationale for a specific feature: [typing source map](./references/index.md)
|
|
|
|
## Load Order
|
|
|
|
1. Start with [typing source map](./references/index.md) for authoritative links.
|
|
2. Load [typing review workflow](./references/review-workflow.md) to execute the review.
|
|
3. Load [Astral ty usage reference](./references/astral-ty.md) when the workflow includes `ty` setup, configuration, migration, or editor integration.
|
|
4. Return to source links for any feature-level recommendation included in the final output.
|
|
|
|
## Load Budget
|
|
|
|
1. Default: load one reference (`index.md`) for lightweight guidance.
|
|
2. Standard review: load two references (`index.md` and `review-workflow.md`).
|
|
3. Add `astral-ty.md` only when `ty` is in scope.
|
|
4. Do not load additional docs unless a project-specific edge case requires it.
|
|
|
|
## Decision Baseline
|
|
|
|
Use these defaults unless a hard compatibility constraint prevents them:
|
|
|
|
1. Prefer built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` and `typing.Dict`.
|
|
2. Prefer `X | Y` over `typing.Optional[X]` or `typing.Union[X, Y]`.
|
|
3. Prefer PEP 695 generics (`class Box[T]`, `def fn[T](...)`) for Python 3.12+ codebases and use them by default.
|
|
4. Prefer `typing.Self` for fluent instance/class method return typing.
|
|
5. Use `typing.Literal` when a finite value set is the real contract.
|
|
6. Remove legacy typing aliases and module-level `TypeVar` declarations when PEP 695 can replace them.
|
|
7. Keep runtime behavior unchanged unless the task explicitly requests behavior refactors.
|
|
8. Treat `typing.cast(...)` as a last resort, not a default fix for type-checker complaints.
|
|
9. Before adding a cast, prefer real narrowing (`isinstance`, `TypeIs`/`TypeGuard`), explicit control-flow checks, or small annotation refactors that preserve behavior.
|
|
10. Reject casts whose only purpose is to silence the checker without a clear runtime invariant.
|
|
11. For closed variant sets (`Literal`/`Enum`/tagged unions), prefer structural pattern matching with exhaustiveness checks (`assert_never`) for deterministic narrowing.
|
|
|
|
## Cast Discipline
|
|
|
|
Use this policy whenever a modernization pass encounters a potential cast:
|
|
|
|
1. Confirm whether the checker can be satisfied with stronger narrowing first (for example `isinstance` or assertion-based narrowing).
|
|
2. If a cast is still necessary, keep it narrowly scoped to the exact expression rather than widening an entire variable flow.
|
|
3. Document the invariant that makes the cast valid in human terms, not just "type checker requires this".
|
|
4. Prefer fixing imprecise annotations at the source over stacking repeated casts downstream.
|
|
5. If multiple casts appear in one code path, treat that as a design smell and propose a structural typing fix.
|
|
|
|
## Completion Checks
|
|
|
|
1. Modern syntax aligns with the project Python baseline.
|
|
2. Linting and diagnostics are clean for edited files.
|
|
3. Public APIs are unchanged unless explicitly requested.
|
|
4. Feature-level recommendations include source links.
|
|
5. Any deferral is backed by a specific hard constraint (for example Python version floor).
|
|
6. New casts, if any, are minimal, justified by an explicit invariant, and not used as checker-silencing shortcuts.
|
|
|
|
## Output Contract
|
|
|
|
Return:
|
|
|
|
1. Files reviewed and files changed.
|
|
2. Applied typing upgrades with brief rationale.
|
|
3. Deferred upgrades only when blocked by explicit hard constraints.
|
|
4. Validation results (lint/tests/diagnostics).
|
|
5. References consulted and discovery path used.
|