ty as Python Type Checker

Python's dynamic typing benefits from static type checking to catch bugs early, improve code documentation, and enable better IDE support.

architectureenforced by 1 rule

Context

Python's dynamic typing benefits from static type checking to catch bugs early, improve code documentation, and enable better IDE support. Several type checkers exist in the Python ecosystem, including mypy (the original, maintained by the Python core team) and pyright (from Microsoft, used in Pylance). However, these tools can be slow on large codebases and have complex configuration requirements.

ty from Astral (the creators of Ruff and UV) is an extremely fast Python type checker written in Rust. It integrates seamlessly with the Ruff/UV toolchain, providing comprehensive type analysis with near-instant feedback. Using ty alongside Ruff for linting and UV for package management creates a unified, high-performance Python toolchain from a single vendor.

Decision

ty is the mandatory Python type checker for all Python code. It replaces mypy and pyright.

All Python packages must include type annotations and pass ty type checking.
ty configuration goes in pyproject.toml under the [tool.ty] section.
ty must be run as part of CI pipelines to enforce type safety.
All functions must have parameter type annotations and return type annotations.
All class attributes must have type annotations.
Use typing module constructs (e.g., Optional, Union, Protocol) for complex types; prefer modern syntax (X | Y) when the minimum Python version supports it.

Do's and Don'ts

Do

Add type annotations to all Python functions and classes.
Run ty as part of CI to catch type errors before merging.
Configure ty in pyproject.toml under [tool.ty].
Use ty check to verify type correctness locally before committing.
Prefer modern type syntax (str | None) over Optional[str] when Python version allows.
Keep the Astral toolchain consistent: Ruff for linting, UV for packages, ty for types.

Don't

Use mypy or pyright as the type checker.
Use # type: ignore comments without a justification comment explaining why.
Leave functions without return type annotations.
Create separate type checker configuration files (mypy.ini, .mypy.ini, pyrightconfig.json).
Skip type checking for new Python modules.

Consequences

Positive

Extremely fast type checking with near-instant feedback, even on large codebases.
Unified Astral toolchain (Ruff + UV + ty) with consistent configuration in pyproject.toml.
Catches type-related bugs early in the development cycle.
Improved code documentation through mandatory type annotations.
Better IDE support and autocompletion from explicit type information.

Negative

ty is a newer tool; some edge cases may not yet be handled compared to mature alternatives.
Developers unfamiliar with Python type annotations face a learning curve.
Strict type checking may require more upfront effort when writing Python code.
Some third-party libraries may lack type stubs, requiring manual type annotations or stubs.

Enforcement rules

adrs/ARCH-003-ty-python-type-checker.rules.ts

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-legacy-type-checker-config": {
      description:
        "No mypy or pyright configuration files allowed — ty is the mandatory type checker",
      async check(ctx) {
        const forbidden = [
          { glob: "packages/jobs/**/mypy.ini", name: "mypy.ini" },
          { glob: "packages/jobs/**/.mypy.ini", name: ".mypy.ini" },
          { glob: "packages/jobs/**/pyrightconfig.json", name: "pyrightconfig.json" },
          { glob: "packages/jobs/**/.pyrightconfig.json", name: ".pyrightconfig.json" },
        ];

        for (const { glob, name } of forbidden) {
          const files = await ctx.glob(glob);
          for (const file of files) {
            ctx.report.violation({
              message: `${file}: legacy type checker config "${name}" found — ty is the mandatory type checker, configured in pyproject.toml`,
              file,
              fix: `Remove ${file} and configure ty in pyproject.toml under [tool.ty]`,
            });
          }
        }

        // Also check for mypy/pyright config sections in pyproject.toml
        const pyprojectFiles = ctx.scopedFiles.filter(
          (f) => f.endsWith("/pyproject.toml") || f.endsWith("\\pyproject.toml"),
        );
        await Promise.all(
          pyprojectFiles.map(async (file) => {
            const content = await ctx.readFile(file);

            if (content.includes("[tool.mypy]")) {
              ctx.report.violation({
                message: `${file}: contains [tool.mypy] configuration — ty is the mandatory type checker`,
                file,
                fix: "Remove [tool.mypy] section and use [tool.ty] instead",
              });
            }

            if (content.includes("[tool.pyright]")) {
              ctx.report.violation({
                message: `${file}: contains [tool.pyright] configuration — ty is the mandatory type checker`,
                file,
                fix: "Remove [tool.pyright] section and use [tool.ty] instead",
              });
            }
          }),
        );
      },
    },
  },
} satisfies RuleSet;