diff --git a/docs/skills/python-typing/SKILL.md b/docs/skills/python-typing/SKILL.md new file mode 100644 index 0000000..091f3f9 --- /dev/null +++ b/docs/skills/python-typing/SKILL.md @@ -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. diff --git a/docs/skills/python-typing/references/index.md b/docs/skills/python-typing/references/index.md new file mode 100644 index 0000000..77f8177 --- /dev/null +++ b/docs/skills/python-typing/references/index.md @@ -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. diff --git a/docs/skills/python-typing/references/review-workflow.md b/docs/skills/python-typing/references/review-workflow.md new file mode 100644 index 0000000..d83ce15 --- /dev/null +++ b/docs/skills/python-typing/references/review-workflow.md @@ -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 ` +- `uv run pytest -q` (or targeted tests where available) + +Use repository-preferred test invocation conventions when they differ.