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.