diff --git a/docs/tooling.md b/docs/tooling.md index 6022f88..521da8c 100644 --- a/docs/tooling.md +++ b/docs/tooling.md @@ -40,6 +40,25 @@ Keep Python configuration in `pyproject.toml`. The Python stack shows Pydantic settings/boundary schemas and Alembic migrations as examples; keep them when they fit the target repo and replace them when an existing choice is better. +The Python stack includes example configuration for MyPy, Pyright, Pyrefly, and +ty, but projects should choose one type checker as the required CI gate. +Recommended defaults: + +- Use Pyrefly for new Python projects that want fast CLI checks and a modern + language server, provided the team is comfortable with its monthly release + cadence and occasional new diagnostics on upgrade. +- Use Pyright when the team already standardizes on VS Code/Pylance, wants a + mature standards-focused checker, or needs strong cross-editor language + server behavior. +- Keep MyPy when the project relies on MyPy plugins, framework-specific typing + behavior, or maximum ecosystem compatibility. +- Use ty only as an advisory or experimental checker until its beta/0.0.x + version policy settles. + +When switching the CI gate, update `stacks/python/scripts/typecheck.sh`, add the +chosen checker to the dev dependency group, and regenerate `uv.lock` with the +repo's supply-chain cooldown policy in mind. + ## Ruby Stack Use Bundler for Ruby installs and command execution when the target project diff --git a/stacks/python/README.md b/stacks/python/README.md index d053ddb..2146bb6 100644 --- a/stacks/python/README.md +++ b/stacks/python/README.md @@ -12,6 +12,8 @@ Python package, or Python-first service tooling. - `scripts/worktree-ports.py`: Python implementation of the worktree port helper. - `scripts/{lint,format,typecheck,test,check-all}.sh`: validation wrappers for this stack. +- Type checker config examples for MyPy, Pyright, Pyrefly, and ty in + `pyproject.toml`. The root devkit uses `scripts/worktree-ports.sh` by default so projects are not forced to include Python just for port allocation. @@ -53,6 +55,11 @@ settings discovery. Python is part of the target runtime or tooling. - Copy `apps/`, `packages/`, `pyproject.toml`, and `uv.lock` together so the workspace and lockfile stay coherent. +- Keep one type checker as the CI gate. The default stack still runs MyPy + because it is mature, Python-native, and has the widest plugin ecosystem. + Prefer Pyrefly for new projects that want a fast modern checker and language + server, Pyright when the team standardizes on Pylance or the Pyright CLI, and + ty as an advisory experiment until it exits beta. - Keep root port helpers shell-based unless the target repo intentionally wants Python helper scripts. - If copying this stack's `scripts/dev.sh`, copy diff --git a/stacks/python/pyproject.toml b/stacks/python/pyproject.toml index 1e44f98..81cef24 100644 --- a/stacks/python/pyproject.toml +++ b/stacks/python/pyproject.toml @@ -81,6 +81,54 @@ warn_redundant_casts = true no_implicit_optional = true ignore_missing_imports = true +# Optional alternative type checker examples. Keep one checker as the +# repository's CI gate, then use the others for editor feedback or migration +# trials. +[tool.pyright] +pythonVersion = "3.12" +typeCheckingMode = "strict" +include = [ + "apps/api/src", + "apps/api/tests", + "packages/shared/src", + "tests", +] +extraPaths = [ + "apps/api/src", + "packages/shared/src", +] +venvPath = "." +venv = ".venv" +reportMissingTypeStubs = "warning" + +[tool.pyrefly] +python-version = "3.12" +project-includes = [ + "apps/api/src", + "apps/api/tests", + "packages/shared/src", + "tests", +] +search-path = [ + "apps/api/src", + "packages/shared/src", +] + +[tool.ty.environment] +python-version = "3.12" +root = [ + "apps/api/src", + "packages/shared/src", +] + +[tool.ty.src] +include = [ + "apps/api/src", + "apps/api/tests", + "packages/shared/src", + "tests", +] + [tool.coverage.run] source = ["example_api", "example_shared"] omit = ["*/tests/*"]