94 lines
4.3 KiB
Markdown
94 lines
4.3 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.
|
|
|
|
## 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).
|
|
|
|
## 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.
|