How astral-sh/ty works
ty is a Rust-backed Python type checker and language server. The principal CLI workflow starts when a developer invokes ty check on a Python project: the packaged executable or Python module launcher resolves the Rust binary, which loads project configuration, analyzes source through the type-system engine, and returns diagnostics and an exit status. An editor provides a parallel LSP workflow for interactive diagnostics, navigation, completions, and fine-grained incremental updates.
Components
Invocation and packaging
• Developer — null: External caller that invokes ty check or starts language-server mode.
• Python module launcher — python/ty/__main__.py: Implements python -m ty; it calls binary discovery and uses execvp on Unix or subprocess.run on Windows.
• Binary discovery — python/ty/_find_ty.py: Searches Python, prefix, adjacent-installation, and user-scheme locations for the compiled ty executable.
• Rust ty executable — ruff: The compiled Rust product; pyproject.toml points maturin at the ruff ty crate, while the README identifies the product as both a type checker and language server.
User-facing project interfaces
• Command-line interface — docs/reference/cli.md: Documents commands, checking modes, output behavior, and CLI options.
• Configuration and project support — docs/reference/configuration.md: Defines the project configuration surface used to control checking behavior.
• Python project — null: External source files, packages, stubs, and configuration supplied for analysis.
Static analysis
• Analysis orchestrator — ruff: Rust implementation layer that coordinates project checking and connects front-end requests to semantic analysis; exact internal call structure is not sampled.
• Type-system semantics — docs/features/type-system.md: Documents narrowing, intersections, reachability, gradual typing, and other semantic rules applied during analysis.
• Diagnostic pipeline — docs/features/diagnostics.md: Defines the contextual diagnostics produced from analysis findings.
• Incremental analysis state — docs/features/language-server.md: Documents fine-grained retained analysis used to make editor updates fast; its concrete storage structures are not visible here.
Language-server consumers
• Language server — docs/features/language-server.md: Provides the LSP capability for diagnostics, navigation, completions, code actions, auto-imports, inlay hints, and hover information.
• Editor client — null: External VS Code, PyCharm, Neovim, or other LSP client.
• Editor integrations — docs/editors.md: Documents how supported editors connect to ty and configure the language-server capability.
Relationships
• Developer -> Rust ty executable: invokes ty check; supported by the README’s getting-started command and the compiled binary packaging.
• Developer -> Python module launcher: may invoke the Python module entry point; evidenced by the module’s executable guard.
• Python module launcher -> Binary discovery: imports and calls find_ty_bin.
• Binary discovery -> Rust ty executable: resolves the executable path from installation layouts.
• Python module launcher -> Rust ty executable: starts the resolved process with the original arguments, using execvp or a Windows subprocess.
• Command-line interface -> Rust ty executable: defines the documented command and option contract exposed by the executable.
• Rust ty executable -> Python project: reads the project’s Python sources and related analysis inputs.
• Rust ty executable -> Configuration and project support: applies project configuration while setting up a check.
• Rust ty executable -> Analysis orchestrator: dispatches CLI checking requests into the Rust analysis implementation.
• Analysis orchestrator -> Type-system semantics: performs semantic type evaluation according to the documented type system.
• Analysis orchestrator -> Diagnostic pipeline: converts analysis findings into user-facing diagnostics.
• Rust ty executable -> Developer: reports diagnostics and command status through the CLI.
• Editor client -> Language server: sends LSP requests and document updates.
• Rust ty executable -> Language server: hosts the language-server mode as an alternative front end to CLI checking.
• Language server -> Analysis orchestrator: translates editor requests into analysis operations.
• Language server -> Incremental analysis state: reads and updates retained analysis state for fine-grained edits.
• Language server -> Editor client: returns diagnostics, navigation results, completions, and other LSP responses.
• Editor integrations -> Editor client: supplies editor-specific setup and connection guidance.
Coverage limits
The sampled repository contains the Python launcher and packaging metadata but not the Rust source inside the ruff submodule. Therefore exact parser, module-resolution, configuration-loading, diagnostic-formatting, caching, and LSP-dispatch internals cannot be established. Release, documentation-generation, and PGO scripts were treated as development tooling rather than product components.
Main entry points: ruff Rust ty Executable · language-server.md Language Server · __main__.py Python Module Launcher · _find_ty.py Binary Discovery
Components 14
Invocation and Packaging
Entry points and executable resolution
- Developer · Invokes CLI or language-server mode
- Python Module Launcher · Implements python -m ty
python/ty/__main__.py - Binary Discovery · Finds the compiled ty executable
python/ty/_find_ty.py - Rust ty Executable · Compiled type checker and language server
ruff
Project Interfaces
CLI, configuration, and analyzed project inputs
- Command-Line Interface · Documents commands and options
docs/reference/cli.md - Configuration and Project Support · Defines project checking configuration
docs/reference/configuration.md - Python Project · Source files, packages, stubs, and configuration
Static Analysis
Type checking and diagnostic production
- Analysis Orchestrator · Coordinates project checking and front-end requests
ruff - Type-System Semantics · Applies documented type-system rules
docs/features/type-system.md - Diagnostic Pipeline · Produces contextual diagnostics
docs/features/diagnostics.md - Incremental Analysis State · Retains fine-grained analysis state
docs/features/language-server.md
Language Server
Interactive editor analysis and LSP communication
- Language Server · Provides interactive language features
docs/features/language-server.md - Editor Client · VS Code, PyCharm, Neovim, or another LSP client
- Editor Integrations · Documents editor setup and connections
docs/editors.md
Connections 18
- Developer → Rust ty Executable: invokes ty check
- Developer → Python Module Launcher: invokes module
- Python Module Launcher → Binary Discovery: calls find_ty_bin
- Binary Discovery → Rust ty Executable: resolves executable
- Python Module Launcher → Rust ty Executable: starts process · Uses execvp on Unix or subprocess.run on Windows
- Command-Line Interface → Rust ty Executable: defines contract
- Rust ty Executable → Python Project: reads inputs
- Rust ty Executable → Configuration and Project Support: applies configuration
- Rust ty Executable → Analysis Orchestrator: dispatches checking
- Analysis Orchestrator → Type-System Semantics: evaluates types
- Analysis Orchestrator → Diagnostic Pipeline: creates diagnostics
- Rust ty Executable → Developer: reports results · Returns diagnostics and command status
- Editor Client → Language Server: sends LSP requests · Includes document updates
- Rust ty Executable → Language Server: hosts mode · Provides language-server mode as an alternative front end
- Language Server → Analysis Orchestrator: translates requests
- Language Server → Incremental Analysis State: updates state · Reads and updates retained analysis state
- Language Server → Editor Client: returns LSP responses · Diagnostics, navigation, completions, and other results
- Editor Integrations → Editor Client: supplies setup · Provides editor-specific connection guidance