From c5b7733528e554a0aa94e73de4fb583d54f1bb43 Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Sun, 21 Jun 2026 15:20:00 -0500 Subject: [PATCH] typing skill improvements --- docs/skills/python-typing/SKILL.md | 8 ++- .../python-typing/references/astral-ty.md | 59 +++++++++++++++++++ docs/skills/python-typing/references/index.md | 5 ++ 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 docs/skills/python-typing/references/astral-ty.md diff --git a/docs/skills/python-typing/SKILL.md b/docs/skills/python-typing/SKILL.md index 091f3f9..374b194 100644 --- a/docs/skills/python-typing/SKILL.md +++ b/docs/skills/python-typing/SKILL.md @@ -24,6 +24,7 @@ Use this skill to enforce a latest-syntax-first typing standard grounded in curr 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 @@ -44,19 +45,22 @@ Load references only when needed: - 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. Return to source links for any feature-level recommendation included in the final output. +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. Do not load additional docs unless a project-specific edge case requires it. +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 diff --git a/docs/skills/python-typing/references/astral-ty.md b/docs/skills/python-typing/references/astral-ty.md new file mode 100644 index 0000000..d12833c --- /dev/null +++ b/docs/skills/python-typing/references/astral-ty.md @@ -0,0 +1,59 @@ +# Astral ty Usage Reference + +Use this page when you want to run or adopt [ty](https://docs.astral.sh/ty/), Astral's Python type checker and language server, in a typing-focused workflow. + +## Quick Start + +- Run a one-off check without installing globally: `uvx ty check` +- Run checks in the current project: `ty check` +- Explore behavior quickly in the [ty playground](https://play.ty.dev/) + +Primary docs: + +- [Getting started](https://docs.astral.sh/ty/#getting-started) +- [Installation](https://docs.astral.sh/ty/installation/) +- [Type checking](https://docs.astral.sh/ty/type-checking/) +- [CLI reference](https://docs.astral.sh/ty/reference/cli/) + +## Editor Integration + +Use ty as a language server in supported editors. + +- [Editor integration overview](https://docs.astral.sh/ty/editors/) +- [VS Code setup](https://docs.astral.sh/ty/editors/#vs-code) +- [Language server capabilities](https://docs.astral.sh/ty/features/language-server/) +- [Editor settings reference](https://docs.astral.sh/ty/reference/editor-settings/) + +## Configuration Surface + +Start from project defaults, then add targeted overrides only where needed. + +- [Configuration guide](https://docs.astral.sh/ty/configuration/) +- [Configuration reference](https://docs.astral.sh/ty/reference/configuration/) +- [Python version handling](https://docs.astral.sh/ty/python-version/) +- [Module discovery](https://docs.astral.sh/ty/modules/) +- [File exclusions](https://docs.astral.sh/ty/exclusions/) + +## Rule And Suppression Controls + +Use this set when tuning signal-to-noise in large or partially typed codebases. + +- [Rules overview](https://docs.astral.sh/ty/rules/) +- [Rules reference](https://docs.astral.sh/ty/reference/rules/) +- [Suppression comments and directives](https://docs.astral.sh/ty/suppression/) +- [Diagnostics feature docs](https://docs.astral.sh/ty/features/diagnostics/) + +## Migration Notes + +For teams moving from existing type checkers, use Astral's migration guidance first. + +- [Coming from mypy or pyright](https://docs.astral.sh/ty/coming-from-mypy-or-pyright/) +- [Typing FAQ](https://docs.astral.sh/ty/reference/typing-faq) + +## Suggested Review Flow With ty + +1. Confirm Python baseline and project targets. +2. Run `uvx ty check` for an initial signal pass. +3. Configure version/module/discovery settings as needed. +4. Triage diagnostics and tune rules or suppressions deliberately. +5. Re-run checks and keep modernization changes behavior-preserving unless explicitly requested. diff --git a/docs/skills/python-typing/references/index.md b/docs/skills/python-typing/references/index.md index 77f8177..f3f9f72 100644 --- a/docs/skills/python-typing/references/index.md +++ b/docs/skills/python-typing/references/index.md @@ -8,6 +8,11 @@ Use this page as the canonical source index when making typing modernization rec - [Typing specification (typing.python.org)](https://typing.python.org/) - [Built-in types and generic aliases](https://docs.python.org/3/library/stdtypes.html) +## Tooling References + +- [Astral ty documentation](https://docs.astral.sh/ty/) +- [Astral ty usage reference (this skill)](./astral-ty.md) + ## Modernization PEPs - [PEP 585: Type Hinting Generics In Standard Collections](https://peps.python.org/pep-0585/)