0
# Language Server
1

2
LSP-compliant language server providing real-time type checking and IntelliSense features for Python development environments.
3

4
## Capabilities
5

6
### Language Server Binary
7

8
The language server binary that implements the Language Server Protocol for editor integration.
9

10
```bash { .api }
11
pyright-langserver
12
```
13

14
**Communication Protocol:**
15
- Uses stdin/stdout for JSON-RPC communication
16
- Implements Language Server Protocol (LSP) specification
17
- Supports both synchronous and asynchronous operations
18

19
### Core LSP Features
20

21
Real-time language services for Python development.
22

23
#### Diagnostics
24

25
```typescript { .api }
26
interface PublishDiagnosticsParams {
27
  uri: string;
28
  diagnostics: Diagnostic[];
29
}
30

31
interface Diagnostic {
32
  range: Range;
33
  severity?: DiagnosticSeverity;
34
  code?: number | string;
35
  source?: string;
36
  message: string;
37
  relatedInformation?: DiagnosticRelatedInformation[];
38
}
39
```
40

41
Provides real-time type checking and error reporting as you type.
42

43
#### Text Completion
44

45
```typescript { .api }
46
interface CompletionParams {
47
  textDocument: TextDocumentIdentifier;
48
  position: Position;
49
  context?: CompletionContext;
50
}
51

52
interface CompletionItem {
53
  label: string;
54
  kind?: CompletionItemKind;
55
  detail?: string;
56
  documentation?: string | MarkupContent;
57
  insertText?: string;
58
  additionalTextEdits?: TextEdit[];
59
}
60
```
61

62
Provides intelligent code completion with:
63
- Variable and function suggestions
64
- Import statement auto-completion
65
- Type-aware member access completion
66
- Auto-import suggestions for missing imports
67

68
#### Hover Information
69

70
```typescript { .api }
71
interface HoverParams {
72
  textDocument: TextDocumentIdentifier;
73
  position: Position;
74
}
75

76
interface Hover {
77
  contents: MarkupContent | MarkedString | MarkedString[];
78
  range?: Range;
79
}
80
```
81

82
Shows type information, documentation, and signatures on hover.
83

84
#### Go to Definition
85

86
```typescript { .api }
87
interface DefinitionParams {
88
  textDocument: TextDocumentIdentifier;
89
  position: Position;
90
}
91

92
type Definition = Location | Location[];
93
```
94

95
Navigate to symbol definitions across files and packages.
96

97
#### Find All References
98

99
```typescript { .api }
100
interface ReferenceParams {
101
  textDocument: TextDocumentIdentifier;
102
  position: Position;
103
  context: ReferenceContext;
104
}
105

106
type References = Location[];
107
```
108

109
Find all usages of symbols throughout the codebase.
110

111
#### Symbol Renaming
112

113
```typescript { .api }
114
interface RenameParams {
115
  textDocument: TextDocumentIdentifier;
116
  position: Position;
117
  newName: string;
118
}
119

120
interface WorkspaceEdit {
121
  changes?: { [uri: string]: TextEdit[] };
122
  documentChanges?: TextDocumentEdit[];
123
}
124
```
125

126
Rename symbols with automatic updates across all references.
127

128
#### Document Symbols
129

130
```typescript { .api }
131
interface DocumentSymbolParams {
132
  textDocument: TextDocumentIdentifier;
133
}
134

135
interface DocumentSymbol {
136
  name: string;
137
  detail?: string;
138
  kind: SymbolKind;
139
  range: Range;
140
  selectionRange: Range;
141
  children?: DocumentSymbol[];
142
}
143
```
144

145
Provides document outline and symbol navigation.
146

147
#### Workspace Symbols
148

149
```typescript { .api }
150
interface WorkspaceSymbolParams {
151
  query: string;
152
}
153

154
interface WorkspaceSymbol {
155
  name: string;
156
  kind: SymbolKind;
157
  location: Location;
158
  containerName?: string;
159
}
160
```
161

162
Search for symbols across the entire workspace.
163

164
#### Signature Help
165

166
```typescript { .api }
167
interface SignatureHelpParams {
168
  textDocument: TextDocumentIdentifier;
169
  position: Position;
170
}
171

172
interface SignatureHelp {
173
  signatures: SignatureInformation[];
174
  activeSignature?: number;
175
  activeParameter?: number;
176
}
177
```
178

179
Shows function signature information during function calls.
180

181
#### Code Actions
182

183
```typescript { .api }
184
interface CodeActionParams {
185
  textDocument: TextDocumentIdentifier;
186
  range: Range;
187
  context: CodeActionContext;
188
}
189

190
interface CodeAction {
191
  title: string;
192
  kind?: string;
193
  diagnostics?: Diagnostic[];
194
  edit?: WorkspaceEdit;
195
  command?: Command;
196
}
197
```
198

199
Provides quick fixes and refactoring actions:
200
- Add missing imports
201
- Fix type annotation issues
202
- Organize imports
203
- Remove unused imports
204

205
#### Call Hierarchy
206

207
```typescript { .api }
208
interface CallHierarchyPrepareParams {
209
  textDocument: TextDocumentIdentifier;
210
  position: Position;
211
}
212

213
interface CallHierarchyItem {
214
  name: string;
215
  kind: SymbolKind;
216
  uri: string;
217
  range: Range;
218
  selectionRange: Range;
219
}
220
```
221

222
View incoming and outgoing call relationships.
223

224
### Configuration Integration
225

226
The language server respects the same configuration files as the CLI:
227

228
```typescript { .api }
229
interface ServerSettings {
230
  // File watching
231
  watchForSourceChanges: boolean;
232
  watchForLibraryChanges: boolean;
233
  watchForConfigChanges: boolean;
234
  
235
  // Analysis scope
236
  openFilesOnly: boolean;
237
  useLibraryCodeForTypes: boolean;
238
  
239
  // Features
240
  disableLanguageServices: boolean;
241
  autoImportCompletions: boolean;
242
  
243
  // Type checking
244
  typeCheckingMode: "off" | "basic" | "standard" | "strict";
245
  diagnosticSeverityOverrides: { [rule: string]: "none" | "information" | "warning" | "error" };
246
  
247
  // Display
248
  functionSignatureDisplay: "compact" | "formatted";
249
  logLevel: "Error" | "Warning" | "Information" | "Trace";
250
}
251
```
252

253
### Editor Integration Examples
254

255
#### Visual Studio Code
256

257
```json
258
{
259
  "python.languageServer": "Pylance",
260
  "python.analysis.typeCheckingMode": "strict",
261
  "python.analysis.autoImportCompletions": true
262
}
263
```
264

265
#### Vim/Neovim with LSP
266

267
```lua
268
require'lspconfig'.pyright.setup{
269
  settings = {
270
    python = {
271
      analysis = {
272
        typeCheckingMode = "strict",
273
        autoSearchPaths = true,
274
        useLibraryCodeForTypes = true
275
      }
276
    }
277
  }
278
}
279
```
280

281
#### Emacs with lsp-mode
282

283
```elisp
284
(use-package lsp-pyright
285
  :ensure t
286
  :hook (python-mode . (lambda ()
287
                         (require 'lsp-pyright)
288
                         (lsp))))
289
```
290

291
### Performance Optimization
292

293
The language server includes several performance optimizations:
294

295
- **Incremental Analysis**: Only re-analyzes changed files and their dependencies
296
- **Background Analysis**: Runs type checking in background threads
297
- **Smart Caching**: Caches analysis results and type information
298
- **File Watching**: Efficiently monitors file system changes
299
- **Lazy Loading**: Loads type information on demand
300

301
### Initialization
302

303
The language server supports standard LSP initialization:
304

305
```typescript { .api }
306
interface InitializeParams {
307
  processId: number | null;
308
  rootPath?: string | null;
309
  rootUri: string | null;
310
  initializationOptions?: any;
311
  capabilities: ClientCapabilities;
312
  workspaceFolders?: WorkspaceFolder[] | null;
313
}
314

315
interface ServerCapabilities {
316
  textDocumentSync?: TextDocumentSyncOptions;
317
  completionProvider?: CompletionOptions;
318
  hoverProvider?: boolean;
319
  definitionProvider?: boolean;
320
  referencesProvider?: boolean;
321
  renameProvider?: RenameOptions;
322
  documentSymbolProvider?: boolean;
323
  workspaceSymbolProvider?: boolean;
324
  signatureHelpProvider?: SignatureHelpOptions;
325
  codeActionProvider?: CodeActionOptions;
326
  callHierarchyProvider?: boolean;
327
}
328
```
329

330
### Error Handling
331

332
The language server handles errors gracefully:
333
- Configuration parsing errors are reported as diagnostics
334
- File access errors are logged and don't crash the server
335
- Type analysis errors are converted to diagnostics
336
- Invalid client requests receive appropriate error responses
337

338
### Multi-root Workspace Support
339

340
Supports multiple project roots in a single workspace:
341
- Each root can have its own configuration
342
- Cross-root references are handled correctly
343
- Workspace-wide symbol search across all roots