feat: add ty backend support for Astral's Python type checker

- Add lsp_types/ty/ module with TyBackend, config schema, and KNOWN_LIMITATIONS.md
- Support nested TOML config sections (environment, src, rules, etc.)
- Implement recursive snake_case to kebab-case key conversion for ty.toml
- Add parametrized tests for ty backend in test_session.py and test_pool.py
- Add ty-specific tests for config serialization and extra_paths
- Mark tests requiring virtual documents as xfail for ty (requires files on disk)
- Add KNOWN_LIMITATIONS.md for Pyrefly backend
- Add INTEGRATION_NOTES.md documenting frictions and enhancement opportunities
- Update README.md and CLAUDE.md with ty documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Mazyod

CLAUDE.md

@@ -83,6 +83,14 @@ This is a minimal-dependency Python library providing typed LSP (Language Server
 - **Key Design**: Uses consolidated `Session` class with `PyreflyBackend` for specialization
 - **Config Flexibility**: Supports arbitrary configuration fields via TOML serialization (using `tomli-w`)
 
+**ty Integration (`lsp_types/ty/`)**
+- `backend.py`: `TyBackend` implementation for ty LSP server (Astral's Rust-based type checker)
+- `config_schema.py`: ty configuration types with nested sections (environment, src, rules, etc.)
+- **Key Design**: Uses consolidated `Session` class with `TyBackend` for specialization
+- **Config Format**: TOML (`ty.toml`) with nested sections and kebab-case keys
+- **Known Limitation**: ty requires files to exist on disk (virtual documents not fully supported)
+- **Documentation**: See `KNOWN_LIMITATIONS.md` in the ty package for details
+
 ### Type Generation Pipeline
 
 **Schema Sources:**
@@ -97,33 +105,34 @@ This is a minimal-dependency Python library providing typed LSP (Language Server
 
 ### Testing Strategy
 
-**Tests are parametrized to run against multiple backends (Pyright and Pyrefly).**
+**Tests are parametrized to run against multiple backends (Pyright, Pyrefly, and ty).**
 
 **Process Pool Tests (`tests/test_pool.py`)**
 - Direct `LSPProcessPool` testing with generic interface
-- Parametrized fixtures for testing both Pyright and Pyrefly backends
+- Parametrized fixtures for testing Pyright, Pyrefly, and ty backends
 - Comprehensive pool behavior testing (creation, recycling, limits, cleanup)
 - Performance benchmarks comparing pooled vs non-pooled sessions
 - Concurrent usage scenarios and idle process management
 
 **Session Tests (`tests/test_session.py`)**
 - Core consolidated Session class functionality
-- Parametrized fixtures for testing both Pyright and Pyrefly backends
+- Parametrized fixtures for testing Pyright, Pyrefly, and ty backends
 - Integration testing with actual language servers (diagnostics, hover, completion)
 - Dynamic environment testing with temporary directories
 - Backend-agnostic tests that validate common LSP operations
+- Backend-specific tests for unique configuration options (e.g., ty's nested config, Pyrefly's search_path)
 
 ### Dependencies
 
 **Runtime:**
-- `tomli-w>=1.0.0` - TOML writing support for Pyrefly configuration serialization
+- `tomli-w>=1.0.0` - TOML writing support for Pyrefly and ty configuration serialization
 
 **Development:** uv-managed dependencies in `pyproject.toml`
 - `pytest` with async support for testing
 - `datamodel-code-generator` for type generation
 - `httpx` for schema downloading
 
-**Note:** Previously a zero-dependency library. Added `tomli-w` to support arbitrary configuration fields in Pyrefly backend.
+**Note:** Previously a zero-dependency library. Added `tomli-w` to support TOML configuration for Pyrefly and ty backends.
 
 ### Examples
 
@@ -135,9 +144,10 @@ The `examples/` directory contains demo scripts showing library usage:
 
 - Always prefix test commands with `uv run`
 - **Before committing**: Run tests (`uv run pytest`), type checking (`uvx pyright`), and linting (`uvx ruff check .`) - CI will fail if any have errors
-- Pool tests require `pyright-langserver` and/or `pyrefly` binaries available in PATH
+- Pool tests require `pyright-langserver`, `pyrefly`, and/or `ty` binaries available in PATH
 - Type generation requires Python 3.12+ for modern TypedDict features
 - Generated types should not be manually edited - regenerate from schemas
+- Each backend has a `KNOWN_LIMITATIONS.md` file documenting backend-specific behaviors
 
 ### Architecture Design Patterns
 

INTEGRATION_NOTES.md

@@ -0,0 +1,155 @@
+# LSP Backend Integration Notes
+
+This document captures frictions and enhancement opportunities discovered while integrating new LSP backends into lsp-python-types.
+
+## ty Backend Integration (January 2026)
+
+### Frictions Encountered
+
+#### 1. Virtual Document Support
+
+**Issue**: ty requires files to exist on disk before it can provide diagnostics, completion, and other features. Pyright and Pyrefly work with "virtual documents" opened via `didOpen` without requiring the file to exist on disk.
+
+**Impact**: Tests that don't write files to disk fail for ty. The following parametrized tests required `xfail` markers for ty:
+- `test_session_diagnostics`
+- `test_session_rename`
+- `test_session_completion`
+- `test_session_recycling_with_diagnostics`
+- `test_session_warmup_on_recycle` (in test_pool.py)
+
+**Workaround**: ty-specific tests must write files to disk using `tmp_path`:
+```python
+(tmp_path / "new.py").write_text(code)
+session = await Session.create(backend, base_path=tmp_path, initial_code=code)
+```
+
+**Potential Enhancement**: Consider adding a `requires_file_on_disk` property to the `LSPBackend` protocol, allowing the Session class to automatically write files when needed.
+
+#### 2. `workspace/didChangeConfiguration` Not Supported
+
+**Issue**: ty logs `Received notification workspace/didChangeConfiguration which does not have a handler.` The Session class sends this notification after initialization to apply workspace settings.
+
+**Impact**: Runtime configuration changes via `didChangeConfiguration` don't work with ty. However, configuration written to `ty.toml` is respected.
+
+**Current Behavior**: The notification is sent but ignored by ty. No functional impact since config file is written first.
+
+**Potential Enhancement**: Add an optional `supports_did_change_configuration` flag to backends so the Session can skip sending this notification when unsupported.
+
+#### 3. Nested Configuration Structure
+
+**Issue**: ty uses nested TOML sections (`[environment]`, `[src]`, `[rules]`) unlike Pyrefly's flat structure. This required implementing recursive key conversion.
+
+**Solution**: Created `_convert_keys_to_kebab()` function in `lsp_types/ty/backend.py`:
+```python
+def _convert_keys_to_kebab(obj: t.Mapping[str, t.Any]) -> dict[str, t.Any]:
+    """Recursively convert dict keys from snake_case to kebab-case."""
+    result: dict[str, t.Any] = {}
+    for key, value in obj.items():
+        kebab_key = key.replace("_", "-")
+        if isinstance(value, dict):
+            result[kebab_key] = _convert_keys_to_kebab(value)
+        elif isinstance(value, list):
+            result[kebab_key] = [
+                _convert_keys_to_kebab(v) if isinstance(v, dict) else v
+                for v in value
+            ]
+        else:
+            result[kebab_key] = value
+    return result
+```
+
+**Potential Enhancement**: Extract this utility to a shared module (`lsp_types/utils.py`) since Pyrefly also uses TOML with kebab-case keys (though currently with flat structure).
+
+#### 4. Hover Information Format Differences
+
+**Issue**: ty's hover response shows just the type (`str`) rather than `variable_name: type` format used by Pyright and Pyrefly.
+
+**Impact**: Test assertions checking for variable names in hover text fail for ty.
+
+**Workaround**: Added backend-specific assertion in `test_session_hover`:
+```python
+if backend_name != "ty":
+    assert "result" in hover_text
+assert "str" in hover_text
+```
+
+#### 5. No CLI Flags for LSP Server
+
+**Issue**: Unlike Pyrefly which accepts `--verbose`, `--threads`, and `--indexing-mode` CLI flags, ty's `server` command accepts no configuration flags.
+
+**Impact**: All configuration must be done via `ty.toml`. This is actually simpler than Pyrefly's hybrid approach.
+
+**Solution**: `create_process_launch_info()` simply returns `["ty", "server"]` without any conditional flag building.
+
+---
+
+## Enhancement Opportunities
+
+### 1. Shared TOML Key Conversion Utility
+
+Both Pyrefly and ty use TOML with kebab-case keys but Python code uses snake_case. Consider creating:
+
+```python
+# lsp_types/utils.py
+def snake_to_kebab_recursive(obj: Mapping[str, Any]) -> dict[str, Any]:
+    """Recursively convert dict keys from snake_case to kebab-case."""
+    # ... implementation
+```
+
+Then refactor both backends to use this shared utility.
+
+### 2. Backend Capability Flags
+
+Add optional flags to the `LSPBackend` protocol for:
+- `requires_file_on_disk: bool` - Whether backend needs files to exist on disk
+- `supports_did_change_configuration: bool` - Whether backend handles `workspace/didChangeConfiguration`
+
+This would allow the Session class to adapt its behavior automatically.
+
+### 3. Common LSP Capabilities Base
+
+Create a helper function for shared capabilities:
+
+```python
+def get_base_python_capabilities() -> types.ClientCapabilities:
+    """Common LSP capabilities for Python type checkers."""
+    return {
+        "textDocument": {
+            "publishDiagnostics": {...},
+            "hover": {...},
+            "signatureHelp": {},
+        }
+    }
+```
+
+Backends could extend this base instead of duplicating the boilerplate.
+
+### 4. Backend Registry Pattern
+
+For easier discovery and testing:
+
+```python
+_BACKENDS: dict[str, type[LSPBackend]] = {}
+
+def register_backend(name: str):
+    def decorator(cls):
+        _BACKENDS[name] = cls
+        return cls
+    return decorator
+
+@register_backend("ty")
+class TyBackend(LSPBackend):
+    ...
+```
+
+---
+
+## Summary
+
+The ty backend integration revealed that different LSP servers have varying requirements around file handling and configuration. The current abstraction works but could benefit from:
+
+1. Optional capability flags on backends
+2. Shared utilities for common patterns (TOML conversion, base capabilities)
+3. Better documentation of backend-specific behaviors
+
+The core `LSPBackend` protocol and `Session` class work well across all three backends (Pyright, Pyrefly, ty) with minimal backend-specific handling needed in tests.

README.md

@@ -62,6 +62,7 @@ The following LSPs are available out of the box:
 
 - [Pyright](https://github.com/microsoft/pyright)
 - [Pyrefly](https://github.com/facebook/pyrefly)
+- [ty](https://github.com/astral-sh/ty) - Astral's fast Python type checker
 
 ### Pyright Example
 

lsp_types/pyrefly/KNOWN_LIMITATIONS.md

@@ -0,0 +1,31 @@
+# Pyrefly Backend - Known Limitations
+
+This document describes known limitations and behavioral differences when using the Pyrefly backend compared to other LSP backends (Pyright, ty).
+
+## 1. Rename Operations Disabled for External Files
+
+**Limitation**: Pyrefly detects files as "external" and disables rename edit functionality.
+
+**Behavior**: Calling `get_rename_edits()` returns `None` or empty edits for files that Pyrefly considers external to the project.
+
+**Impact**: Symbol renaming may not work in certain project configurations.
+
+**Status**: Marked as xfail in tests pending investigation.
+
+## 2. Completion Item Resolution Not Supported
+
+**Limitation**: Pyrefly does not support the `completionItem/resolve` LSP request.
+
+**Behavior**: Calling `resolve_completion()` may return the item unchanged without additional details.
+
+**Impact**: Completion items won't have extended documentation or additional metadata that resolution typically provides.
+
+## 3. Configuration Key Format
+
+**Note**: Pyrefly uses TOML configuration (`pyrefly.toml`) with kebab-case keys (e.g., `python-version`, `search-path`). The backend automatically converts snake_case Python keys to kebab-case when writing the config file.
+
+---
+
+## Version Information
+
+These limitations were documented based on Pyrefly version 0.32.0+. Future versions may address some of these limitations.

lsp_types/ty/KNOWN_LIMITATIONS.md

@@ -0,0 +1,89 @@
+# ty Backend - Known Limitations
+
+This document describes known limitations and behavioral differences when using the ty backend compared to other LSP backends (Pyright, Pyrefly).
+
+## 1. Files Must Exist on Disk
+
+**Limitation**: ty requires Python files to exist on disk before it can provide diagnostics, completion, rename, and other analysis features.
+
+**Behavior**: Opening a "virtual document" via `didOpen` without a corresponding file on disk results in:
+- Empty diagnostics (no errors reported even for invalid code)
+- Empty or limited completion results
+- Rename operations may fail
+
+**Workaround**: Always write files to disk before creating a session:
+```python
+from pathlib import Path
+
+base_path = Path("/tmp/my_project")
+base_path.mkdir(exist_ok=True)
+
+code = "x: int = 'not an int'"
+(base_path / "new.py").write_text(code)
+
+session = await Session.create(
+    TyBackend(),
+    base_path=base_path,
+    initial_code=code,
+)
+diagnostics = await session.get_diagnostics()  # Now returns errors
+```
+
+## 2. `workspace/didChangeConfiguration` Not Supported
+
+**Limitation**: ty does not handle the `workspace/didChangeConfiguration` notification.
+
+**Behavior**: ty logs a warning:
+```
+WARN Received notification workspace/didChangeConfiguration which does not have a handler.
+```
+
+**Impact**: Runtime configuration changes via LSP notifications are ignored. However, configuration written to `ty.toml` before session creation is respected.
+
+**Workaround**: Ensure all configuration is set in `ty.toml` via the `options` parameter when creating a session. If configuration needs to change, create a new session.
+
+## 3. Hover Format Differs
+
+**Limitation**: ty's hover information shows only the type, not the variable name.
+
+**Behavior**:
+- Pyright/Pyrefly hover: `result: str` or `(variable) result: str`
+- ty hover: `str`
+
+**Impact**: Code that parses hover text expecting variable names will not find them with ty.
+
+## 4. No CLI Configuration Flags
+
+**Limitation**: The `ty server` command accepts no configuration flags.
+
+**Behavior**: Unlike Pyrefly which supports `--verbose`, `--threads`, etc., ty's LSP server is configured entirely via `ty.toml`.
+
+**Impact**: No impact on functionality - all configuration works via the config file.
+
+## 5. Workspace Folders Warning
+
+**Limitation**: ty expects `workspaceFolders` in the initialization parameters.
+
+**Behavior**: ty logs a warning when workspaceFolders is not provided:
+```
+WARN No workspace(s) were provided during initialization. Using the current working directory from the fallback system as a default workspace
+```
+
+**Impact**: ty falls back to using the working directory. This typically works correctly but may affect multi-root workspace scenarios.
+
+## 6. File Watching Not Supported by Client
+
+**Limitation**: The current LSP client implementation doesn't support file watching.
+
+**Behavior**: ty logs:
+```
+WARN Your LSP client doesn't support file watching: You may see stale results when files change outside the editor
+```
+
+**Impact**: If files are modified outside the LSP session (e.g., by external tools), ty may not detect the changes until the session is recreated.
+
+---
+
+## Version Information
+
+These limitations were documented based on ty version 0.0.11 (January 2026). Future versions may address some of these limitations.

lsp_types/ty/__init__.py

@@ -0,0 +1,4 @@
+from .backend import TyBackend
+from .config_schema import Model as TyConfig
+
+__all__ = ["TyBackend", "TyConfig"]