python typing skill

2026-06-21 12:37:19 -05:00
parent 9a9432cc55
commit 9c8ab70c06
3 changed files with 162 additions and 0 deletions
@@ -0,0 +1,89 @@
 ---
 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)
 ## 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)
 - 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. 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. 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.
@@ -0,0 +1,28 @@
 # Python Typing Source Map
 Use this page as the canonical source index when making typing modernization recommendations.
 ## Core Language and Library Docs
 - [Typing module documentation](https://docs.python.org/3/library/typing.html)
 - [Typing specification (typing.python.org)](https://typing.python.org/)
 - [Built-in types and generic aliases](https://docs.python.org/3/library/stdtypes.html)
 ## Modernization PEPs
 - [PEP 585: Type Hinting Generics In Standard Collections](https://peps.python.org/pep-0585/)
 - [PEP 604: Allow writing union types as `X | Y`](https://peps.python.org/pep-0604/)
 - [PEP 673: Self Type](https://peps.python.org/pep-0673/)
 - [PEP 695: Type Parameter Syntax](https://peps.python.org/pep-0695/)
 ## Advanced Typing PEPs (Load on Demand)
 - [PEP 612: Parameter Specification Variables](https://peps.python.org/pep-0612/)
 - [PEP 646: Variadic Generics](https://peps.python.org/pep-0646/)
 - [PEP 647: User-Defined Type Guards](https://peps.python.org/pep-0647/)
 - [PEP 655: Required and NotRequired for TypedDict](https://peps.python.org/pep-0655/)
 - [PEP 742: Narrowing types with TypeIs](https://peps.python.org/pep-0742/)
 ## Version Gate Reminder
 Before recommending syntax upgrades, verify the project's supported Python range and lint target so recommendations match runtime constraints.
@@ -0,0 +1,45 @@
 # Typing Review Workflow
 This workflow is distilled from practical typing modernization passes and is designed for latest-syntax-first upgrades.
 ## Step-by-Step Process
 1. Identify the Python baseline from project config (`requires-python`, lint target version, toolchain constraints).
 2. Scan target files for legacy typing patterns and repeated opportunities.
 3. Apply highest-value modern syntax updates first:
   - `typing.List`/`typing.Dict` -> built-in generics.
   - `Optional[T]`/`Union[A, B]` -> `T | None` / `A | B`.
 4. Upgrade generic declarations to PEP 695 syntax where baseline allows:
   - `TypeVar` module globals -> local type parameters in classes/functions.
 5. Tighten domain contracts where clear:
   - replace unconstrained `str` with `Literal[...]` for finite known values.
   - use `Self` for fluent APIs.
 6. Keep edits minimal and avoid behavior changes unless requested.
 7. Validate with lint and editor diagnostics.
 8. Report applied changes, hard-blocker deferrals, and sources consulted.
 ## Decision Points and Branching
 - If Python baseline is below 3.12:
  - use the newest syntax available under that baseline, and document exactly what blocked PEP 695.
 - If a legacy annotation is public API and downstream tooling compatibility is unknown:
  - still modernize syntax unless there is a confirmed breakage risk with a named downstream constraint.
 - If replacing `TypeVar` with PEP 695 affects readability debates only:
  - still prefer PEP 695; readability preference alone is not a blocker.
 - If a stricter type (for example `Literal`) may reject existing runtime inputs:
  - apply only when the input contract is already finite; otherwise defer with a contract-change note.
 ## Quality Criteria
 1. All edits are syntax-valid for the target Python versions.
 2. Lint and diagnostics pass for edited files.
 3. Runtime behavior is unchanged for modernization-only tasks.
 4. Recommendations cite authoritative sources.
 5. Output clearly separates "changed now" from hard-blocked follow-up items.
 ## Suggested Validation Commands
 - `uv run ruff check <paths>`
 - `uv run pytest -q` (or targeted tests where available)
 Use repository-preferred test invocation conventions when they differ.