CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pyright

Static type checker for Python with command-line tool and language server capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

language-server.mddocs/

Language Server

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

Capabilities

Language Server Binary

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

pyright-langserver

Communication Protocol:

  • Uses stdin/stdout for JSON-RPC communication
  • Implements Language Server Protocol (LSP) specification
  • Supports both synchronous and asynchronous operations

Core LSP Features

Real-time language services for Python development.

Diagnostics

interface PublishDiagnosticsParams {
  uri: string;
  diagnostics: Diagnostic[];
}

interface Diagnostic {
  range: Range;
  severity?: DiagnosticSeverity;
  code?: number | string;
  source?: string;
  message: string;
  relatedInformation?: DiagnosticRelatedInformation[];
}

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

Text Completion

interface CompletionParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
  context?: CompletionContext;
}

interface CompletionItem {
  label: string;
  kind?: CompletionItemKind;
  detail?: string;
  documentation?: string | MarkupContent;
  insertText?: string;
  additionalTextEdits?: TextEdit[];
}

Provides intelligent code completion with:

  • Variable and function suggestions
  • Import statement auto-completion
  • Type-aware member access completion
  • Auto-import suggestions for missing imports

Hover Information

interface HoverParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
}

interface Hover {
  contents: MarkupContent | MarkedString | MarkedString[];
  range?: Range;
}

Shows type information, documentation, and signatures on hover.

Go to Definition

interface DefinitionParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
}

type Definition = Location | Location[];

Navigate to symbol definitions across files and packages.

Find All References

interface ReferenceParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
  context: ReferenceContext;
}

type References = Location[];

Find all usages of symbols throughout the codebase.

Symbol Renaming

interface RenameParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
  newName: string;
}

interface WorkspaceEdit {
  changes?: { [uri: string]: TextEdit[] };
  documentChanges?: TextDocumentEdit[];
}

Rename symbols with automatic updates across all references.

Document Symbols

interface DocumentSymbolParams {
  textDocument: TextDocumentIdentifier;
}

interface DocumentSymbol {
  name: string;
  detail?: string;
  kind: SymbolKind;
  range: Range;
  selectionRange: Range;
  children?: DocumentSymbol[];
}

Provides document outline and symbol navigation.

Workspace Symbols

interface WorkspaceSymbolParams {
  query: string;
}

interface WorkspaceSymbol {
  name: string;
  kind: SymbolKind;
  location: Location;
  containerName?: string;
}

Search for symbols across the entire workspace.

Signature Help

interface SignatureHelpParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
}

interface SignatureHelp {
  signatures: SignatureInformation[];
  activeSignature?: number;
  activeParameter?: number;
}

Shows function signature information during function calls.

Code Actions

interface CodeActionParams {
  textDocument: TextDocumentIdentifier;
  range: Range;
  context: CodeActionContext;
}

interface CodeAction {
  title: string;
  kind?: string;
  diagnostics?: Diagnostic[];
  edit?: WorkspaceEdit;
  command?: Command;
}

Provides quick fixes and refactoring actions:

  • Add missing imports
  • Fix type annotation issues
  • Organize imports
  • Remove unused imports

Call Hierarchy

interface CallHierarchyPrepareParams {
  textDocument: TextDocumentIdentifier;
  position: Position;
}

interface CallHierarchyItem {
  name: string;
  kind: SymbolKind;
  uri: string;
  range: Range;
  selectionRange: Range;
}

View incoming and outgoing call relationships.

Configuration Integration

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

interface ServerSettings {
  // File watching
  watchForSourceChanges: boolean;
  watchForLibraryChanges: boolean;
  watchForConfigChanges: boolean;
  
  // Analysis scope
  openFilesOnly: boolean;
  useLibraryCodeForTypes: boolean;
  
  // Features
  disableLanguageServices: boolean;
  autoImportCompletions: boolean;
  
  // Type checking
  typeCheckingMode: "off" | "basic" | "standard" | "strict";
  diagnosticSeverityOverrides: { [rule: string]: "none" | "information" | "warning" | "error" };
  
  // Display
  functionSignatureDisplay: "compact" | "formatted";
  logLevel: "Error" | "Warning" | "Information" | "Trace";
}

Editor Integration Examples

Visual Studio Code

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "strict",
  "python.analysis.autoImportCompletions": true
}

Vim/Neovim with LSP

require'lspconfig'.pyright.setup{
  settings = {
    python = {
      analysis = {
        typeCheckingMode = "strict",
        autoSearchPaths = true,
        useLibraryCodeForTypes = true
      }
    }
  }
}

Emacs with lsp-mode

(use-package lsp-pyright
  :ensure t
  :hook (python-mode . (lambda ()
                         (require 'lsp-pyright)
                         (lsp))))

Performance Optimization

The language server includes several performance optimizations:

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

Initialization

The language server supports standard LSP initialization:

interface InitializeParams {
  processId: number | null;
  rootPath?: string | null;
  rootUri: string | null;
  initializationOptions?: any;
  capabilities: ClientCapabilities;
  workspaceFolders?: WorkspaceFolder[] | null;
}

interface ServerCapabilities {
  textDocumentSync?: TextDocumentSyncOptions;
  completionProvider?: CompletionOptions;
  hoverProvider?: boolean;
  definitionProvider?: boolean;
  referencesProvider?: boolean;
  renameProvider?: RenameOptions;
  documentSymbolProvider?: boolean;
  workspaceSymbolProvider?: boolean;
  signatureHelpProvider?: SignatureHelpOptions;
  codeActionProvider?: CodeActionOptions;
  callHierarchyProvider?: boolean;
}

Error Handling

The language server handles errors gracefully:

  • Configuration parsing errors are reported as diagnostics
  • File access errors are logged and don't crash the server
  • Type analysis errors are converted to diagnostics
  • Invalid client requests receive appropriate error responses

Multi-root Workspace Support

Supports multiple project roots in a single workspace:

  • Each root can have its own configuration
  • Cross-root references are handled correctly
  • Workspace-wide symbol search across all roots

Install with Tessl CLI

npx tessl i tessl/npm-pyright

docs

cli-tool.md

index.md

json-output.md

language-server.md

tile.json