0
# ty
1

2
An extremely fast Python type checker and language server written in Rust. ty provides comprehensive type checking for Python codebases with advanced error reporting, configuration options, and Language Server Protocol support for seamless editor integration.
3

4
## Package Information
5

6
- **Package Name**: ty
7
- **Package Type**: pypi
8
- **Language**: Python (with Rust backend)
9
- **Installation**: `pip install ty` or `uv tool install ty` or `pipx install ty`
10
- **Version**: 0.0.1-alpha.20
11
- **License**: MIT
12
- **Repository**: https://github.com/astral-sh/ty
13
- **Documentation**: https://docs.astral.sh/ty/
14

15
## Core Imports
16

17
The ty package can be imported as a Python module but provides minimal programmatic API:
18

19
```python
20
import ty
21
```
22

23
However, ty is primarily used as a command-line tool:
24

25
```bash
26
ty check
27
```
28

29
## Basic Usage
30

31
```bash
32
# Basic type checking
33
ty check
34

35
# Check specific files
36
ty check src/main.py tests/
37

38
# Watch mode with auto-recheck
39
ty check --watch
40

41
# Use specific Python version
42
ty check --python-version 3.11
43

44
# Start language server
45
ty server
46
```
47

48
For project integration:
49

50
```bash
51
# Add to project as dev dependency
52
uv add --dev ty
53

54
# Run with uv
55
uv run ty check
56
```
57

58
## Architecture
59

60
ty consists of several key components:
61

62
- **Type Checker Core**: Rust-based high-performance type analysis engine
63
- **CLI Interface**: Command-line interface for type checking operations
64
- **Language Server**: LSP implementation for real-time editor integration
65
- **Configuration System**: Flexible TOML-based configuration for projects
66
- **Module Resolution**: Sophisticated Python package and module discovery
67
- **Binary Wrapper**: Python wrapper that locates and executes the Rust binary
68

69
The architecture prioritizes performance through Rust implementation while maintaining compatibility with Python tooling and ecosystems.
70

71
## Capabilities
72

73
### Command Line Interface
74

75
Core command-line functionality for type checking, language server operation, and tool management.
76

77
```bash { .api }
78
# Main command
79
ty <COMMAND>
80

81
# Type checking
82
ty check [OPTIONS] [PATHS]...
83

84
# Language server
85
ty server
86

87
# Version information
88
ty version
89

90
# Shell completion
91
ty generate-shell-completion <SHELL>
92

93
# Help
94
ty help [COMMAND]
95
```
96

97
**Arguments:**
98
- `PATHS`: List of files or directories to check (optional, defaults to project root)
99
- `SHELL`: Shell type for completion generation (bash, zsh, fish, powershell, elvish)
100
- `COMMAND`: Subcommand to get help for (optional)
101

102
**Global Options for `ty check`:**
103

104
File and path options:
105
- `--project <project>`: Run within specific project directory
106
- `--exclude <exclude>`: Glob patterns to exclude from checking
107

108
Python environment options:
109
- `--python <path>`: Path to Python environment or interpreter. ty uses this to resolve type information and third-party dependencies. If not specified, ty attempts to infer from VIRTUAL_ENV/CONDA_PREFIX or discover .venv directory. If interpreter path is provided (e.g., .venv/bin/python3), ty attempts to find environment two directories up. Does not invoke interpreter, so won't resolve dynamic executables like shims.
110
- `--python-version <version>`, `--target-version <version>`: Target Python version (3.7-3.13). If not specified, ty tries: 1) project.requires-python in pyproject.toml, 2) infer from Python environment, 3) fallback to 3.13
111
- `--python-platform <platform>`, `--platform <platform>`: Target platform (win32/darwin/linux/android/ios/all). Used to specialize sys.platform type. If 'all', no platform assumptions are made. Defaults to current system platform.
112
- `--extra-search-path <path>`: Additional module resolution paths (can be repeated)
113
- `--typeshed <path>`, `--custom-typeshed-dir <path>`: Custom typeshed directory for standard library types
114

115
Configuration options:
116
- `--config-file <path>`: Path to ty.toml configuration file
117
- `--config <config-option>`, `-c <config-option>`: TOML key=value configuration override
118

119
Rule control options:
120
- `--error <rule>`: Treat rule as error-level (can be repeated)
121
- `--warn <rule>`: Treat rule as warning-level (can be repeated)
122
- `--ignore <rule>`: Disable rule (can be repeated)
123

124
Output options:
125
- `--output-format <format>`: Message format (full/concise)
126
- `--color <when>`: Color output control (auto/always/never)
127
- `--quiet/-q`: Quiet output (use -qq for silent)
128
- `--verbose/-v`: Verbose output (use -vv, -vvv for more verbose)
129
- `--help/-h`: Print help information
130

131
Behavior options:
132
- `--watch/-W`: Watch mode for continuous checking
133
- `--error-on-warning`: Exit code 1 on warnings
134
- `--exit-zero`: Always exit with code 0
135
- `--respect-ignore-files`: Respect file exclusions via .gitignore and other standard ignore files (use --no-respect-gitignore to disable)
136

137
### Python Module API
138

139
Limited programmatic access through Python module wrapper.
140

141
```python { .api }
142
def find_ty_bin() -> str:
143
    """
144
    Return the ty binary path.
145
    
146
    Searches various installation locations including:
147
    - System scripts directory
148
    - User-specific installation paths
149
    - Virtual environment paths
150
    - pip build environments
151
    - Adjacent bin directories
152
    
153
    Returns:
154
        str: Absolute path to ty binary executable
155
        
156
    Raises:
157
        FileNotFoundError: If ty binary cannot be located
158
    """
159
```
160

161
**Usage Example:**
162
```python
163
from ty import find_ty_bin
164
import subprocess
165

166
# Get ty binary path
167
ty_path = find_ty_bin()
168

169
# Run type checking programmatically
170
result = subprocess.run([ty_path, "check", "src/"], capture_output=True, text=True)
171
print(result.stdout)
172
```
173

174
### Configuration System
175

176
Comprehensive TOML-based configuration supporting project-level and user-level settings.
177

178
```toml { .api }
179
# pyproject.toml format
180
[tool.ty.rules]
181
rule_name = "ignore" | "warn" | "error"
182

183
[tool.ty.environment]
184
extra-paths = ["./shared/my-search-path"]
185
python = "./.venv"
186
python-platform = "win32" | "darwin" | "android" | "ios" | "linux" | "all"
187
python-version = "3.7" | "3.8" | "3.9" | "3.10" | "3.11" | "3.12" | "3.13"
188
root = ["./src", "./lib"]
189
typeshed = "/path/to/custom/typeshed"
190

191
[tool.ty.src]
192
include = ["src", "tests"]
193
exclude = ["generated", "*.proto", "tests/fixtures/**"]  # Additional excludes beyond defaults
194
respect-ignore-files = true
195

196
[tool.ty.terminal]
197
output-format = "full" | "concise"
198
error-on-warning = false
199

200
[[tool.ty.overrides]]
201
include = ["tests/**"]
202
exclude = ["tests/fixtures/**"]
203

204
[tool.ty.overrides.rules]
205
rule_name = "ignore" | "warn" | "error"
206
```
207

208
**Configuration File Locations:**
209
- Project: `pyproject.toml` (under `[tool.ty]`) or `ty.toml`
210
- User: `~/.config/ty/ty.toml` or `$XDG_CONFIG_HOME/ty/ty.toml` (Linux/macOS)
211
- User: `%APPDATA%\ty\ty.toml` (Windows)
212

213
**Precedence:** Command line > project config > user config
214

215
### Language Server Protocol
216

217
Language server implementation providing real-time type checking and editor integration.
218

219
```bash { .api }
220
# Start language server
221
ty server
222
```
223

224
**LSP Features:**
225
- Real-time type checking as you type
226
- Diagnostic reporting with error/warning details
227
- Hover information for type details
228
- Go-to-definition support
229
- Symbol search and workspace analysis
230
- Configuration synchronization
231

232
**Editor Integration:**
233

234
VS Code:
235
```json
236
{
237
  "ty.enable": true,
238
  "ty.path": "/path/to/ty",
239
  "ty.settings": {
240
    "python-version": "3.11"
241
  }
242
}
243
```
244

245
Neovim (nvim-lspconfig):
246
```lua
247
require('lspconfig').ty.setup({
248
  settings = {
249
    ty = {
250
      -- ty language server settings
251
    }
252
  }
253
})
254
```
255

256
Neovim 0.11+ (vim.lsp.config):
257
```lua
258
vim.lsp.config('ty', {
259
  settings = {
260
    ty = {
261
      -- ty language server settings
262
    }
263
  }
264
})
265
vim.lsp.enable('ty')
266
```
267

268
### Environment Variables
269

270
Environment variables that control ty's behavior and configuration.
271

272
```bash { .api }
273
# Configuration file path
274
export TY_CONFIG_FILE="/path/to/ty.toml"
275

276
# Python environment detection
277
export VIRTUAL_ENV="/path/to/venv"
278
export CONDA_PREFIX="/path/to/conda/env"
279
```
280

281
**Environment Variables:**
282
- `TY_CONFIG_FILE`: Override configuration file location
283
- `VIRTUAL_ENV`: Active virtual environment path (auto-detected)
284
- `CONDA_PREFIX`: Conda environment path (auto-detected)
285

286
### Exit Codes
287

288
ty uses standard exit codes to indicate the result of operations.
289

290
```bash { .api }
291
# Exit codes
292
0  # Success (no errors, or only warnings without --error-on-warning)
293
1  # Type errors found, or warnings with --error-on-warning
294
2  # Configuration or runtime errors
295
```
296

297
## Module Discovery
298

299
ty implements sophisticated module resolution for Python projects:
300

301
### First-party Modules
302
- Searches project root and `src/` directories by default
303
- Configurable via `environment.root` setting
304
- Supports src-layout, flat-layout, and custom project structures
305
- Automatically includes `tests/` if it's not a package
306

307
### Third-party Modules
308
- Resolves from configured Python environment
309
- Searches `site-packages` directories
310
- Supports virtual environments and conda environments
311
- Uses `--python` or auto-discovery via `VIRTUAL_ENV`/`CONDA_PREFIX`
312

313
### Standard Library
314
- Uses built-in typeshed stubs (bundled as zip in binary)
315
- Version-specific based on target Python version
316
- Customizable via `--typeshed` option
317

318
## Rule System
319

320
ty provides a comprehensive rule system for type checking configuration:
321

322
### Rule Categories
323
- Type compatibility and assignment checking
324
- Import resolution and missing import detection
325
- Attribute access validation
326
- Function call signature validation
327
- Variable binding and scope analysis
328

329
### Rule Configuration
330
```toml
331
[tool.ty.rules]
332
# Examples of common rules
333
possibly-unresolved-reference = "warn"
334
division-by-zero = "ignore"
335
index-out-of-bounds = "error"
336
redundant-cast = "ignore"
337
unused-ignore-comment = "warn"
338
```
339

340
### Rule Overrides
341
```toml
342
# File-specific rule overrides
343
[[tool.ty.overrides]]
344
include = ["tests/**", "**/test_*.py"]
345

346
[tool.ty.overrides.rules]
347
possibly-unresolved-reference = "ignore"  # Relax for tests
348
```
349

350
## Performance Features
351

352
ty is optimized for speed and efficiency:
353

354
- **Rust Implementation**: Core type checker written in Rust for maximum performance
355
- **Incremental Checking**: Only re-analyzes changed files and dependencies
356
- **Watch Mode**: Continuous checking with file system monitoring
357
- **Fast Startup**: Minimal initialization overhead
358
- **Memory Efficient**: Optimized memory usage for large codebases
359
- **Parallel Analysis**: Multi-threaded processing where possible
360

361
## Integration Patterns
362

363
### CI/CD Integration
364
```yaml
365
# GitHub Actions example
366
- name: Type check with ty
367
  run: |
368
    uv tool install ty
369
    ty check --error-on-warning
370
```
371

372
### Pre-commit Hook
373
```yaml
374
# .pre-commit-config.yaml
375
repos:
376
  - repo: https://github.com/astral-sh/ty
377
    rev: v0.0.1-alpha.20
378
    hooks:
379
      - id: ty
380
```
381

382
### Development Workflow
383
```bash
384
# Development commands
385
ty check --watch          # Continuous checking
386
ty check --verbose        # Detailed output
387
ty check src/ tests/      # Specific paths
388
ty check --python .venv   # Specific environment
389
```
390

391
### Editor Integration
392
- **VS Code**: Official extension (astral-sh.ty)
393
- **Neovim**: Built-in LSP support
394
- **Vim**: LSP client configuration
395
- **Emacs**: lsp-mode integration
396
- **Any LSP-compatible editor**: Generic LSP server support
397

398
## Types
399

400
```python { .api }
401
# Configuration types (for reference)
402
RuleName = str  # Rule identifier (e.g., "possibly-unresolved-reference")
403
Severity = "ignore" | "warn" | "error"
404
PythonVersion = "3.7" | "3.8" | "3.9" | "3.10" | "3.11" | "3.12" | "3.13"
405
Platform = "win32" | "darwin" | "android" | "ios" | "linux" | "all"
406
OutputFormat = "full" | "concise"
407
ColorOption = "auto" | "always" | "never"
408

409
# Path specifications
410
Path = str  # File or directory path
411
GlobPattern = str  # Gitignore-style pattern
412
```