Python Lsp

python-lsp

A thin, dependency-free Python client that owns the LSP lifecycle against

pyright-langserver --stdio and exposes high-value semantic queries.

Why, over tree-sitter / ripgrep: tree-sitter gives a CST — structural

queries, call-site enumeration by name. It cannot do name resolution, type

inference, or cross-file binding. ripgrep matches text, so it false-positives

on shadowed / same-named symbols. pyright resolves bindings. This client is

that semantic overlay.

Setup (self-installing)

The client bootstraps pyright on first use. Run the bootstrap explicitly, or

let LSPClient do it via ensure_pyright():

sh /mnt/skills/user/python-lsp/scripts/bootstrap.sh
# or, equivalently, the one-liner it wraps:
command -v pyright-langserver >/dev/null || uv tool install pyright

pyright wheels vendor the langserver JS bundle and run it on system node —

no npm install, no separate fetch when node is present. Measured cold (caches

wiped): uv tool install pyright ~0.7s, first working server ~1.8s total; warm

sub-second.

Node prerequisite. The clean path assumes system node (v18+) is present.

With no node, pyright-python falls back to downloading node from nodejs.org,

which may be blocked in locked-down containers. The bootstrap detects node and

fails loudly (exit 1, clear message) rather than hanging.

Usage: CLI

LSP=/mnt/skills/user/python-lsp/scripts/lsp_client.py

python3 $LSP bootstrap                              # ensure pyright installed
python3 $LSP <root> definition  <file> <line> <col>
python3 $LSP <root> references  <file> <line> <col>
python3 $LSP <root> hover       <file> <line> <col>
python3 $LSP <root> diagnostics <file>
python3 $LSP <root> symbols     <file>             # documentSymbol outline
python3 $LSP <root> wsymbols    <query>            # workspace/symbol search

Positions are zero-based line/character (LSP spec). <file> is relative to

<root> or absolute.

Usage: library

The scripts/ module lands on the boot .pth, so it is importable directly.

import sys; sys.path.insert(0, "/mnt/skills/user/python-lsp/scripts")
from lsp_client import LSPClient

with LSPClient("/path/to/repo") as c:        # context manager reaps the subprocess
    c.open_all("pkg/service.py", "pkg/models.py")
    c.wait_for_index()                       # REQUIRED before querying — see below
    defs  = c.definition("pkg/service.py", 4, 8)   # -> [Location], follows imports
    refs  = c.references("pkg/models.py", 8, 4)     # -> [Location], binding-resolved
    typ   = c.hover("pkg/service.py", 4, 4)         # -> "(variable) u: User"
    diags = c.diagnostics("pkg/bad.py")             # -> [diagnostic dicts]
    outln = c.document_symbols("pkg/models.py")     # -> [SymbolInfo], file outline
    hits  = c.workspace_symbols("User")             # -> [SymbolInfo], project-wide

Location has .path, .start_line, .start_char, .end_line, .end_char

(all zero-based) and .as_dict(). Convert 1-based UI input with

Position.from_one_based(line, col).

The root you pass is split into two roles. Relative <file> arguments resolve

against it (call that the *scope*), but pyright is rooted at the enclosing

project root — by default LSPClient climbs out of any package the scope

sits inside (every ancestor with an __init__.py) via find_project_root. This

is what makes a query scoped to a sub-package (scipy/optimize) still resolve

the project's own absolute imports (from scipy.optimize._x import Y); without

it, references silently undercount — same blindness as a text grep, opposite

direction. The promotion is announced on stderr. Pass auto_root=False to pin

pyright at the scope verbatim.

Methods

| Method | Returns | Notes |

|---|---|---|

| definition(file, line, col) | list[Location] | Go-to-definition across files/imports. |

| references(file, line, col) | list[Location] | Binding-resolved — the win over ripgrep. Excludes same-named, unrelated symbols. |

| hover(file, line, col) | str \| None | Inferred type / signature string. |

| diagnostics(file) | list[dict] | pyright type/error diagnostics for the file. |

| document_symbols(file) | list[SymbolInfo] | One file's outline (classes/functions/methods); nesting via .container. |

| workspace_symbols(query) | list[SymbolInfo] | Project-wide fuzzy symbol search. Empty query = every symbol (expensive). |

SymbolInfo has .name, .kind (int), .kind_name (e.g. "Class"), .location (a Location), .container, and .as_dict().

The lifecycle gotchas (the parts that bite)

• Wait for indexing before querying. Querying mid-index returns empty

results — the most common silent failure. wait_for_index() blocks on

pyright's $/progress begin/end cycle (with a diagnostics-arrival fallback).

Always call it after did_open / open_all and before any query.

• Don't advertise workspace.configuration or workspace.workspaceFolders.

If the client claims either capability, pyright defers *all* analysis until

the corresponding negotiation completes — the server starts its service

instance and then goes silent (no diagnostics, no progress, queries hang).

start() advertises neither, so pyright uses its defaults and analyzes open

files immediately — no didChangeConfiguration nudge needed. Relevant if you

reimplement the lifecycle or add capabilities. (Bisected against the fixture;

workspace.symbol is safe to advertise.)

• Reap the subprocess. Use the context manager (or call stop()) so

sessions don't leak pyright-langserver processes. stop() sends

shutdown + exit, then waits/terminates/kills as needed.

• Open the files you query. Queries auto-did_open their target file, but

for cross-file references open all relevant files first so pyright has

built their models.

• Root at the project, not the sub-package. pyright resolves absolute

intra-project imports only when rooted where the top-level package is

importable. Rooted at a sub-package, those imports fail and references

undercount with no error. LSPClient auto-detects this (climbs out of the

enclosing package; see find_project_root) and prints the promotion to

stderr; auto_root=False opts out. This was a live silent-undercount bug:

--refs ScalarFunction over scipy/optimize returned 3 references rooted at

the sub-package vs 30 rooted at the project root.

Tests

cd /mnt/skills/user/python-lsp
python3 -m pytest tests/test_lsp_client.py -v

Round-trips against tests/fixture/ (a small multi-file package): definition

follows an import, references excludes an unrelated same-named symbol, hover

returns an inferred type, diagnostics flags an intentional type error, the

indexing-wait is verified deterministic, and subprocess cleanup is checked for

orphans.