name: using-python-lsp
description: Use when working with Python code and pyright-lsp plugin is enabled - for finding references, checking types, navigating definitions, or verifying type correctness

Using Python LSP

Overview

The pyright-lsp plugin provides semantic code intelligence for Python. Use LSP tools instead of grep/read when you need semantic accuracy - LSP understands Python's type system, inheritance, and symbol relationships.

When to Use LSP vs Text Search

digraph lsp_decision {
    "Need code info?" [shape=diamond];
    "Semantic accuracy needed?" [shape=diamond];
    "Use LSP tool" [shape=box];
    "Use Grep/Read" [shape=box];

    "Need code info?" -> "Semantic accuracy needed?" [label="yes"];
    "Need code info?" -> "Use Grep/Read" [label="no - text patterns"];
    "Semantic accuracy needed?" -> "Use LSP tool" [label="yes"];
    "Semantic accuracy needed?" -> "Use Grep/Read" [label="no"];
}

Use LSP for:
- Finding all usages before refactoring
- Getting type information
- Navigating to definitions
- Checking for type errors

Use Grep for:
- Text patterns (comments, strings, config)
- Cross-language searches
- When LSP unavailable

LSP Operations Quick Reference

Key Patterns

Before Refactoring: Find All References

Wrong approach:

Grep for "method_name" -> may miss aliased calls, get false positives

Right approach:

LSP findReferences on method -> gets ALL semantic usages, no false positives

Getting Type Information

Wrong approach:

Read file -> find function -> parse return annotation manually

Right approach:

LSP hover on symbol -> instant type signature with docs

Verifying Type Correctness

Wrong approach:

Bash: pipx run mypy src/ (slow, external tool)

Right approach:

LSP getDiagnostics on changed files -> instant, no external process

Common Mistakes

How LSP Tools Work

LSP is a built-in Claude Code tool, not a bash command. When pyright-lsp plugin is enabled, Claude Code automatically provides these operations:
- goToDefinition - navigate to where symbol is defined
- findReferences - find all usages of a symbol
- hover - get type signature and documentation
- getDiagnostics - get type errors for a file
- documentSymbol - list all symbols in a file

You invoke these through Claude's tool system, not via bash. If LSP is unavailable, fall back to grep/read but document the limitation.

Prerequisites

1. Plugin enabled: pyright-lsp@claude-plugins-official in ~/.claude/settings.json
2. Pyright installed: pip install pyright or npm install -g pyright
3. Project configured: pyproject.toml or pyrightconfig.json present (recommended)

Fallback Strategy

If LSP is unavailable (tool not found, server not running):

1. Document the limitation - note that you're using text search as fallback
2. Use Grep with caution - understand it may miss aliased calls or inheritance
3. Verify manually - for refactoring, double-check results make sense semantically
4. Suggest fix - remind user to ensure pyright is installed and plugin enabled

Red Flags - Stop and Use LSP

These thoughts mean you should use LSP, not grep:

When LSP Won't Help

• No pyright binary installed
• Working with dynamic Python (heavy eval, exec, __getattr__)
• Cross-language references
• Comment/docstring searches
• Projects without type hints (LSP works but limited value)