Light‑weight CodeLens provider that shows how many times a Python function / method / class is referenced in your workspace (PyCharm style). Click the indicator to open the built‑in references panel and navigate.
✨ Features
Function / method / class reference counting (per symbol)
Semantic symbol detection via the language server's document‑symbol provider, with a regex scan as fallback when no server is available
Counts are de‑duplicated and the definition is excluded by default for accurate totals
Reference resolution is deferred until a CodeLens is revealed and cached per document version, so scrolling stays fast
Detects when no Python language server is present and offers (once) to install the official Python extension, then upgrades counts automatically once it loads
Scope counting to classes only, functions/methods only, or both
Optionally hide CodeLens when count is zero
⚙️ Settings
All settings are under pythonReferenceCounter namespace:
Setting
Type
Default
Description
pythonReferenceCounter.showZeroReferences
boolean
true
Show CodeLens even for zero references
pythonReferenceCounter.enableFor
enum
both
Which symbols get CodeLens: both, classes, or functions (functions + methods)
Safety net used only when no Python language server resolves a symbol (extension missing or still indexing): a naive full-workspace text search. Slower and may over-count; skipped entirely when the server returns results
📦 Requirements
VS Code >= 1.102.0
Recommended: the official Python extension (bundles Pylance). It provides the semantic symbol and reference data this extension reads via vscode.executeDocumentSymbolProvider / vscode.executeReferenceProvider — this is what makes counts both accurate and fast. The extension detects when no Python server is present and offers to install it (once).
Without any Python language server, the extension still works in a degraded mode: a regex scan finds definitions and an optional workspace text scan estimates counts (slower, less accurate).
🚀 Usage
Install the extension
Open a Python file
Hover near a function / class line or scroll it into view – a CodeLens like 3 references appears
Click the lens to open the references panel
Adjust behavior via Settings > Extensions > Python Reference Counter
🧠 How It Works (Brief)
Provide phase: vscode.executeDocumentSymbolProvider enumerates classes / functions / methods semantically (exact name ranges, correct kinds). If no language server responds, a cheap regex scan is used instead. Each symbol becomes a placeholder CodeLens.
Resolve phase: when a lens becomes visible, vscode.executeReferenceProvider returns the references, which are de‑duplicated. For the regex fallback, method references are additionally post‑filtered to true call sites (preceded by .); semantic references are trusted as‑is.
The slow workspace text scan runs only when the language server resolves nothing for a symbol (no server, or not yet indexed). When the server returns results they are used directly — no whole‑workspace file opening.
The definition itself is always excluded from the count (matching the "N references" convention); zero‑count hiding is applied per user settings, and the resulting count is cached for the current document version.
📌 Limitations / Notes
Static analysis only—dynamic usages via getattr, reflection, metaprogramming not detected
Method detection relies on a .method call heuristic; very unusual formatting may reduce accuracy
The fallback workspace scan (used only when no language server resolves a symbol) is plain text matching and may over‑count occurrences inside comments or strings
Decorators on their own lines do not affect detection; multi‑line def(...) signatures are matched by their opening line
