ty CLI

ty's user-facing binary. Source: crates/ty/.

Purpose

ty is Astral's Python type checker, in the same shape as ruff but built around an incremental Salsa database. The CLI is a thin shell that loads a project, walks files, and reports diagnostics.

Directory layout

crates/ty/src/
├── main.rs              # binary entry point
├── lib.rs
├── args.rs              # clap arguments
├── logging.rs
├── printer.rs           # diagnostic output
├── python_version.rs    # version detection helpers
├── rule.rs              # rule listings, --explain
├── version.rs
└── snapshots/           # CLI snapshot tests

The binary defers most of the heavy lifting to crates/ty_python_semantic (type inference + checks), crates/ty_project (project loading), and crates/ty_server (LSP).

Subcommands

Subcommand	Description
check	Type-check a file or project.
server	Start the ty LSP server.
version	Print version.
--help	Top-level help.

The CLI lives at crates/ty/src/args.rs. Some subcommands accept Python-version overrides (--python-version), --exclude, and rule selectors.

How ty check works

sequenceDiagram
    actor User
    participant CLI as ty (crates/ty)
    participant Project as ty_project::Project
    participant Db as ProjectDatabase
    participant Sem as ty_python_semantic
    participant Diag

    User->>CLI: ty check src/
    CLI->>Project: discover ty.toml / pyproject.toml
    Project->>Db: build ProjectDatabase (salsa)
    CLI->>Db: enumerate Python files
    loop per file (rayon-parallel where possible)
        CLI->>Sem: lint::check_file(db, file)
        Sem->>Db: salsa::tracked queries (infer types, scopes)
        Db-->>Sem: cached or freshly computed answers
        Sem-->>CLI: diagnostics
    end
    CLI->>Diag: render
    Diag-->>User: text / concise / JSON

Because Salsa caches everything, repeated ty check runs in the same process (such as the language server) recompute only the files affected by edits.

Configuration

ty reads:

• [tool.ty] in pyproject.toml
• A standalone ty.toml file
• The bundled JSON schema at ty.schema.json (regenerated via cargo dev generate-all)

Options include python-version, target Python interpreter (used to resolve site-packages and typeshed shims), include/exclude globs, and rule selectors.

Diagnostics

Diagnostic identifiers live alongside each check in crates/ty_python_semantic/src/lint.rs and the types/ modules. Each diagnostic has:

• A short identifier (e.g. invalid-assignment, unsupported-operator)
• A primary span and message
• Optional secondary annotations and subdiagnostics

Output formats mirror Ruff's: text, concise, JSON. --output-format selects between them.

Entry points for modification

• Add a CLI flag: edit crates/ty/src/args.rs.
• Add a subcommand: add a module under crates/ty/src/, dispatch from main.rs.
• Change project discovery: edit crates/ty_project.
• Add a type check or refine inference: see ty_python_semantic.
• Adjust rule listing/--explain output: crates/ty/src/rule.rs.

For LSP capabilities, see ty_server. For the type system itself, see ty_python_semantic.